/**
* Classes, which help reading streams of data from files.
* Based on the classes from Danilo Segan
*
* @version $Id: streams.php 1157 2015-11-20 04:30:11Z dd32 $
* @package pomo
* @subpackage streams
*/
if ( ! class_exists( 'POMO_Reader', false ) ) :
#[AllowDynamicProperties]
class POMO_Reader {
public $endian = 'little';
public $_pos;
public $is_overloaded;
/**
* PHP5 constructor.
*/
public function __construct() {
if ( function_exists( 'mb_substr' )
&& ( (int) ini_get( 'mbstring.func_overload' ) & 2 ) // phpcs:ignore PHPCompatibility.IniDirectives.RemovedIniDirectives.mbstring_func_overloadDeprecated
) {
$this->is_overloaded = true;
} else {
$this->is_overloaded = false;
}
$this->_pos = 0;
}
/**
* PHP4 constructor.
*
* @deprecated 5.4.0 Use __construct() instead.
*
* @see POMO_Reader::__construct()
*/
public function POMO_Reader() {
_deprecated_constructor( self::class, '5.4.0', static::class );
self::__construct();
}
/**
* Sets the endianness of the file.
*
* @param string $endian Set the endianness of the file. Accepts 'big', or 'little'.
*/
public function setEndian( $endian ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
$this->endian = $endian;
}
/**
* Reads a 32bit Integer from the Stream
*
* @return mixed The integer, corresponding to the next 32 bits from
* the stream of false if there are not enough bytes or on error
*/
public function readint32() {
$bytes = $this->read( 4 );
if ( 4 !== $this->strlen( $bytes ) ) {
return false;
}
$endian_letter = ( 'big' === $this->endian ) ? 'N' : 'V';
$int = unpack( $endian_letter, $bytes );
return reset( $int );
}
/**
* Reads an array of 32-bit Integers from the Stream
*
* @param int $count How many elements should be read
* @return mixed Array of integers or false if there isn't
* enough data or on error
*/
public function readint32array( $count ) {
$bytes = $this->read( 4 * $count );
if ( 4 * $count !== $this->strlen( $bytes ) ) {
return false;
}
$endian_letter = ( 'big' === $this->endian ) ? 'N' : 'V';
return unpack( $endian_letter . $count, $bytes );
}
/**
* @param string $input_string
* @param int $start
* @param int $length
* @return string
*/
public function substr( $input_string, $start, $length ) {
if ( $this->is_overloaded ) {
return mb_substr( $input_string, $start, $length, 'ascii' );
} else {
return substr( $input_string, $start, $length );
}
}
/**
* @param string $input_string
* @return int
*/
public function strlen( $input_string ) {
if ( $this->is_overloaded ) {
return mb_strlen( $input_string, 'ascii' );
} else {
return strlen( $input_string );
}
}
/**
* @param string $input_string
* @param int $chunk_size
* @return array
*/
public function str_split( $input_string, $chunk_size ) {
if ( ! function_exists( 'str_split' ) ) {
$length = $this->strlen( $input_string );
$out = array();
for ( $i = 0; $i < $length; $i += $chunk_size ) {
$out[] = $this->substr( $input_string, $i, $chunk_size );
}
return $out;
} else {
return str_split( $input_string, $chunk_size );
}
}
/**
* @return int
*/
public function pos() {
return $this->_pos;
}
/**
* @return true
*/
public function is_resource() {
return true;
}
/**
* @return true
*/
public function close() {
return true;
}
}
endif;
if ( ! class_exists( 'POMO_FileReader', false ) ) :
class POMO_FileReader extends POMO_Reader {
/**
* File pointer resource.
*
* @var resource|false
*/
public $_f;
/**
* @param string $filename
*/
public function __construct( $filename ) {
parent::__construct();
$this->_f = fopen( $filename, 'rb' );
}
/**
* PHP4 constructor.
*
* @deprecated 5.4.0 Use __construct() instead.
*
* @see POMO_FileReader::__construct()
*/
public function POMO_FileReader( $filename ) {
_deprecated_constructor( self::class, '5.4.0', static::class );
self::__construct( $filename );
}
/**
* @param int $bytes
* @return string|false Returns read string, otherwise false.
*/
public function read( $bytes ) {
return fread( $this->_f, $bytes );
}
/**
* @param int $pos
* @return bool
*/
public function seekto( $pos ) {
if ( -1 === fseek( $this->_f, $pos, SEEK_SET ) ) {
return false;
}
$this->_pos = $pos;
return true;
}
/**
* @return bool
*/
public function is_resource() {
return is_resource( $this->_f );
}
/**
* @return bool
*/
public function feof() {
return feof( $this->_f );
}
/**
* @return bool
*/
public function close() {
return fclose( $this->_f );
}
/**
* @return string
*/
public function read_all() {
return stream_get_contents( $this->_f );
}
}
endif;
if ( ! class_exists( 'POMO_StringReader', false ) ) :
/**
* Provides file-like methods for manipulating a string instead
* of a physical file.
*/
class POMO_StringReader extends POMO_Reader {
public $_str = '';
/**
* PHP5 constructor.
*/
public function __construct( $str = '' ) {
parent::__construct();
$this->_str = $str;
$this->_pos = 0;
}
/**
* PHP4 constructor.
*
* @deprecated 5.4.0 Use __construct() instead.
*
* @see POMO_StringReader::__construct()
*/
public function POMO_StringReader( $str = '' ) {
_deprecated_constructor( self::class, '5.4.0', static::class );
self::__construct( $str );
}
/**
* @param string $bytes
* @return string
*/
public function read( $bytes ) {
$data = $this->substr( $this->_str, $this->_pos, $bytes );
$this->_pos += $bytes;
if ( $this->strlen( $this->_str ) < $this->_pos ) {
$this->_pos = $this->strlen( $this->_str );
}
return $data;
}
/**
* @param int $pos
* @return int
*/
public function seekto( $pos ) {
$this->_pos = $pos;
if ( $this->strlen( $this->_str ) < $this->_pos ) {
$this->_pos = $this->strlen( $this->_str );
}
return $this->_pos;
}
/**
* @return int
*/
public function length() {
return $this->strlen( $this->_str );
}
/**
* @return string
*/
public function read_all() {
return $this->substr( $this->_str, $this->_pos, $this->strlen( $this->_str ) );
}
}
endif;
if ( ! class_exists( 'POMO_CachedFileReader', false ) ) :
/**
* Reads the contents of the file in the beginning.
*/
class POMO_CachedFileReader extends POMO_StringReader {
/**
* PHP5 constructor.
*/
public function __construct( $filename ) {
parent::__construct();
$this->_str = file_get_contents( $filename );
if ( false === $this->_str ) {
return false;
}
$this->_pos = 0;
}
/**
* PHP4 constructor.
*
* @deprecated 5.4.0 Use __construct() instead.
*
* @see POMO_CachedFileReader::__construct()
*/
public function POMO_CachedFileReader( $filename ) {
_deprecated_constructor( self::class, '5.4.0', static::class );
self::__construct( $filename );
}
}
endif;
if ( ! class_exists( 'POMO_CachedIntFileReader', false ) ) :
/**
* Reads the contents of the file in the beginning.
*/
class POMO_CachedIntFileReader extends POMO_CachedFileReader {
/**
* PHP5 constructor.
*/
public function __construct( $filename ) {
parent::__construct( $filename );
}
/**
* PHP4 constructor.
*
* @deprecated 5.4.0 Use __construct() instead.
*
* @see POMO_CachedIntFileReader::__construct()
*/
public function POMO_CachedIntFileReader( $filename ) {
_deprecated_constructor( self::class, '5.4.0', static::class );
self::__construct( $filename );
}
}
endif;
/**
* Taxonomy API: Core category-specific template tags
*
* @package WordPress
* @subpackage Template
* @since 1.2.0
*/
/**
* Retrieves category link URL.
*
* @since 1.0.0
*
* @see get_term_link()
*
* @param int|object $category Category ID or object.
* @return string Link on success, empty string if category does not exist.
*/
function get_category_link( $category ) {
if ( ! is_object( $category ) ) {
$category = (int) $category;
}
$category = get_term_link( $category );
if ( is_wp_error( $category ) ) {
return '';
}
return $category;
}
/**
* Retrieves category parents with separator.
*
* @since 1.2.0
* @since 4.8.0 The `$visited` parameter was deprecated and renamed to `$deprecated`.
*
* @param int $category_id Category ID.
* @param bool $link Optional. Whether to format with link. Default false.
* @param string $separator Optional. How to separate categories. Default '/'.
* @param bool $nicename Optional. Whether to use nice name for display. Default false.
* @param array $deprecated Not used.
* @return string|WP_Error A list of category parents on success, WP_Error on failure.
*/
function get_category_parents( $category_id, $link = false, $separator = '/', $nicename = false, $deprecated = array() ) {
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '4.8.0' );
}
$format = $nicename ? 'slug' : 'name';
$args = array(
'separator' => $separator,
'link' => $link,
'format' => $format,
);
return get_term_parents_list( $category_id, 'category', $args );
}
/**
* Retrieves post categories.
*
* This tag may be used outside The Loop by passing a post ID as the parameter.
*
* Note: This function only returns results from the default "category" taxonomy.
* For custom taxonomies use get_the_terms().
*
* @since 0.71
*
* @param int $post_id Optional. The post ID. Defaults to current post ID.
* @return WP_Term[] Array of WP_Term objects, one for each category assigned to the post.
*/
function get_the_category( $post_id = false ) {
$categories = get_the_terms( $post_id, 'category' );
if ( ! $categories || is_wp_error( $categories ) ) {
$categories = array();
}
$categories = array_values( $categories );
foreach ( array_keys( $categories ) as $key ) {
_make_cat_compat( $categories[ $key ] );
}
/**
* Filters the array of categories to return for a post.
*
* @since 3.1.0
* @since 4.4.0 Added the `$post_id` parameter.
*
* @param WP_Term[] $categories An array of categories to return for the post.
* @param int|false $post_id The post ID.
*/
return apply_filters( 'get_the_categories', $categories, $post_id );
}
/**
* Retrieves category name based on category ID.
*
* @since 0.71
*
* @param int $cat_id Category ID.
* @return string|WP_Error Category name on success, WP_Error on failure.
*/
function get_the_category_by_ID( $cat_id ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
$cat_id = (int) $cat_id;
$category = get_term( $cat_id );
if ( is_wp_error( $category ) ) {
return $category;
}
return ( $category ) ? $category->name : '';
}
/**
* Retrieves category list for a post in either HTML list or custom format.
*
* Generally used for quick, delimited (e.g. comma-separated) lists of categories,
* as part of a post entry meta.
*
* For a more powerful, list-based function, see wp_list_categories().
*
* @since 1.5.1
*
* @see wp_list_categories()
*
* @global WP_Rewrite $wp_rewrite WordPress rewrite component.
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
* Default empty string.
* @param int $post_id Optional. ID of the post to retrieve categories for. Defaults to the current post.
* @return string Category list for a post.
*/
function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
global $wp_rewrite;
if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', '', $separator, $parents );
}
/**
* Filters the categories before building the category list.
*
* @since 4.4.0
*
* @param WP_Term[] $categories An array of the post's categories.
* @param int|false $post_id ID of the post to retrieve categories for.
* When `false`, defaults to the current post in the loop.
*/
$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
if ( empty( $categories ) ) {
/** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
}
$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
$thelist = '';
if ( '' === $separator ) {
$thelist .= '';
foreach ( $categories as $category ) {
$thelist .= "\n\t";
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '' . $category->name . ' ';
break;
case 'single':
$thelist .= '';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= $category->name . ' ';
break;
case '':
default:
$thelist .= '' . $category->name . ' ';
}
}
$thelist .= ' ';
} else {
$i = 0;
foreach ( $categories as $category ) {
if ( 0 < $i ) {
$thelist .= $separator;
}
switch ( strtolower( $parents ) ) {
case 'multiple':
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, true, $separator );
}
$thelist .= '' . $category->name . ' ';
break;
case 'single':
$thelist .= '';
if ( $category->parent ) {
$thelist .= get_category_parents( $category->parent, false, $separator );
}
$thelist .= "$category->name ";
break;
case '':
default:
$thelist .= '' . $category->name . ' ';
}
++$i;
}
}
/**
* Filters the category or list of categories.
*
* @since 1.2.0
*
* @param string $thelist List of categories for the current post.
* @param string $separator Separator used between the categories.
* @param string $parents How to display the category parents. Accepts 'multiple',
* 'single', or empty.
*/
return apply_filters( 'the_category', $thelist, $separator, $parents );
}
/**
* Checks if the current post is within any of the given categories.
*
* The given categories are checked against the post's categories' term_ids, names and slugs.
* Categories given as integers will only be checked against the post's categories' term_ids.
*
* Prior to v2.5 of WordPress, category names were not supported.
* Prior to v2.7, category slugs were not supported.
* Prior to v2.7, only one category could be compared: in_category( $single_category ).
* Prior to v2.7, this function could only be used in the WordPress Loop.
* As of 2.7, the function can be used anywhere if it is provided a post ID or post object.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 1.2.0
* @since 2.7.0 The `$post` parameter was added.
*
* @param int|string|int[]|string[] $category Category ID, name, slug, or array of such
* to check against.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post is in any of the given categories.
*/
function in_category( $category, $post = null ) {
if ( empty( $category ) ) {
return false;
}
return has_category( $category, $post );
}
/**
* Displays category list for a post in either HTML list or custom format.
*
* @since 0.71
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents. Accepts 'multiple', 'single', or empty.
* Default empty string.
* @param int $post_id Optional. ID of the post to retrieve categories for. Defaults to the current post.
*/
function the_category( $separator = '', $parents = '', $post_id = false ) {
echo get_the_category_list( $separator, $parents, $post_id );
}
/**
* Retrieves category description.
*
* @since 1.0.0
*
* @param int $category Optional. Category ID. Defaults to the current category ID.
* @return string Category description, if available.
*/
function category_description( $category = 0 ) {
return term_description( $category );
}
/**
* Displays or retrieves the HTML dropdown list of categories.
*
* The 'hierarchical' argument, which is disabled by default, will override the
* depth argument, unless it is true. When the argument is false, it will
* display all of the categories. When it is enabled it will use the value in
* the 'depth' argument.
*
* @since 2.1.0
* @since 4.2.0 Introduced the `value_field` argument.
* @since 4.6.0 Introduced the `required` argument.
* @since 6.1.0 Introduced the `aria_describedby` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct()
* for information on additional accepted arguments.
*
* @type string $show_option_all Text to display for showing all categories. Default empty.
* @type string $show_option_none Text to display for showing no categories. Default empty.
* @type string $option_none_value Value to use when no category is selected. Default empty.
* @type string $orderby Which column to use for ordering categories. See get_terms() for a list
* of accepted values. Default 'id' (term_id).
* @type bool $pad_counts See get_terms() for an argument description. Default false.
* @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents.
* Default 0.
* @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
* bool equivalents. Default 1.
* @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool
* equivalents. Default 0.
* @type int $depth Maximum depth. Default 0.
* @type int $tab_index Tab index for the select element. Default 0 (no tabindex).
* @type string $name Value for the 'name' attribute of the select element. Default 'cat'.
* @type string $id Value for the 'id' attribute of the select element. Defaults to the value
* of `$name`.
* @type string $class Value for the 'class' attribute of the select element. Default 'postform'.
* @type int|string $selected Value of the option that should be selected. Default 0.
* @type string $value_field Term field that should be used to populate the 'value' attribute
* of the option elements. Accepts any valid term field: 'term_id', 'name',
* 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description',
* 'parent', 'count'. Default 'term_id'.
* @type string|array $taxonomy Name of the taxonomy or taxonomies to retrieve. Default 'category'.
* @type bool $hide_if_empty True to skip generating markup if no categories are found.
* Default false (create select element even if no categories are found).
* @type bool $required Whether the `` element should have the HTML5 'required' attribute.
* Default false.
* @type Walker $walker Walker object to use to build the output. Default empty which results in a
* Walker_CategoryDropdown instance being used.
* @type string $aria_describedby The 'id' of an element that contains descriptive text for the select.
* Default empty string.
* }
* @return string HTML dropdown list of categories.
*/
function wp_dropdown_categories( $args = '' ) {
$defaults = array(
'show_option_all' => '',
'show_option_none' => '',
'orderby' => 'id',
'order' => 'ASC',
'show_count' => 0,
'hide_empty' => 1,
'child_of' => 0,
'exclude' => '',
'echo' => 1,
'selected' => 0,
'hierarchical' => 0,
'name' => 'cat',
'id' => '',
'class' => 'postform',
'depth' => 0,
'tab_index' => 0,
'taxonomy' => 'category',
'hide_if_empty' => false,
'option_none_value' => -1,
'value_field' => 'term_id',
'required' => false,
'aria_describedby' => '',
);
$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
// Back compat.
if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
_deprecated_argument(
__FUNCTION__,
'3.0.0',
sprintf(
/* translators: 1: "type => link", 2: "taxonomy => link_category" */
__( '%1$s is deprecated. Use %2$s instead.' ),
'type => link',
'taxonomy => link_category'
)
);
$args['taxonomy'] = 'link_category';
}
// Parse incoming $args into an array and merge it with $defaults.
$parsed_args = wp_parse_args( $args, $defaults );
$option_none_value = $parsed_args['option_none_value'];
if ( ! isset( $parsed_args['pad_counts'] ) && $parsed_args['show_count'] && $parsed_args['hierarchical'] ) {
$parsed_args['pad_counts'] = true;
}
$tab_index = $parsed_args['tab_index'];
$tab_index_attribute = '';
if ( (int) $tab_index > 0 ) {
$tab_index_attribute = " tabindex=\"$tab_index\"";
}
// Avoid clashes with the 'name' param of get_terms().
$get_terms_args = $parsed_args;
unset( $get_terms_args['name'] );
$categories = get_terms( $get_terms_args );
$name = esc_attr( $parsed_args['name'] );
$class = esc_attr( $parsed_args['class'] );
$id = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;
$required = $parsed_args['required'] ? 'required' : '';
$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';
if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
$output = "\n";
} else {
$output = '';
}
if ( empty( $categories ) && ! $parsed_args['hide_if_empty'] && ! empty( $parsed_args['show_option_none'] ) ) {
/**
* Filters a taxonomy drop-down display element.
*
* A variety of taxonomy drop-down display elements can be modified
* just prior to display via this filter. Filterable arguments include
* 'show_option_none', 'show_option_all', and various forms of the
* term name.
*
* @since 1.2.0
*
* @see wp_dropdown_categories()
*
* @param string $element Category name.
* @param WP_Term|null $category The category object, or null if there's no corresponding category.
*/
$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
$output .= "\t$show_option_none \n";
}
if ( ! empty( $categories ) ) {
if ( $parsed_args['show_option_all'] ) {
/** This filter is documented in wp-includes/category-template.php */
$show_option_all = apply_filters( 'list_cats', $parsed_args['show_option_all'], null );
$selected = ( '0' === (string) $parsed_args['selected'] ) ? " selected='selected'" : '';
$output .= "\t$show_option_all \n";
}
if ( $parsed_args['show_option_none'] ) {
/** This filter is documented in wp-includes/category-template.php */
$show_option_none = apply_filters( 'list_cats', $parsed_args['show_option_none'], null );
$selected = selected( $option_none_value, $parsed_args['selected'], false );
$output .= "\t$show_option_none \n";
}
if ( $parsed_args['hierarchical'] ) {
$depth = $parsed_args['depth']; // Walk the full depth.
} else {
$depth = -1; // Flat.
}
$output .= walk_category_dropdown_tree( $categories, $depth, $parsed_args );
}
if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
$output .= " \n";
}
/**
* Filters the taxonomy drop-down output.
*
* @since 2.1.0
*
* @param string $output HTML output.
* @param array $parsed_args Arguments used to build the drop-down.
*/
$output = apply_filters( 'wp_dropdown_cats', $output, $parsed_args );
if ( $parsed_args['echo'] ) {
echo $output;
}
return $output;
}
/**
* Displays or retrieves the HTML list of categories.
*
* @since 2.1.0
* @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments.
* @since 4.4.0 The `current_category` argument was modified to optionally accept an array of values.
* @since 6.1.0 Default value of the 'use_desc_for_title' argument was changed from 1 to 0.
*
* @param array|string $args {
* Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct()
* for information on additional accepted arguments.
*
* @type int|int[] $current_category ID of category, or array of IDs of categories, that should get the
* 'current-cat' class. Default 0.
* @type int $depth Category depth. Used for tab indentation. Default 0.
* @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their
* bool equivalents. Default 1.
* @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude.
* If `$hierarchical` is true, descendants of `$exclude` terms will also
* be excluded; see `$exclude_tree`. See get_terms().
* Default empty string.
* @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude, along
* with their descendants. See get_terms(). Default empty string.
* @type string $feed Text to use for the feed link. Default 'Feed for all posts filed
* under [cat name]'.
* @type string $feed_image URL of an image to use for the feed link. Default empty string.
* @type string $feed_type Feed type. Used to build feed link. See get_term_feed_link().
* Default empty string (default feed).
* @type bool $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in
* the list. Default false (title will always be shown).
* @type string $separator Separator between links. Default '` element. Pass an empty string
* to disable. Default 'Categories'.
* @type bool|int $use_desc_for_title Whether to use the category description as the title attribute.
* Accepts 0, 1, or their bool equivalents. Default 0.
* @type Walker $walker Walker object to use to build the output. Default empty which results
* in a Walker_Category instance being used.
* }
* @return void|string|false Void if 'echo' argument is true, HTML list of categories if 'echo' is false.
* False if the taxonomy does not exist.
*/
function wp_list_categories( $args = '' ) {
$defaults = array(
'child_of' => 0,
'current_category' => 0,
'depth' => 0,
'echo' => 1,
'exclude' => '',
'exclude_tree' => '',
'feed' => '',
'feed_image' => '',
'feed_type' => '',
'hide_empty' => 1,
'hide_title_if_empty' => false,
'hierarchical' => true,
'order' => 'ASC',
'orderby' => 'name',
'separator' => ' ' . $parsed_args['title_li'] . '';
}
if ( empty( $categories ) ) {
if ( ! empty( $show_option_none ) ) {
if ( 'list' === $parsed_args['style'] ) {
$output .= '' . $show_option_none . ' ';
} else {
$output .= $show_option_none;
}
}
} else {
if ( ! empty( $show_option_all ) ) {
$posts_page = '';
// For taxonomies that belong only to custom post types, point to a valid archive.
$taxonomy_object = get_taxonomy( $parsed_args['taxonomy'] );
if ( ! in_array( 'post', $taxonomy_object->object_type, true ) && ! in_array( 'page', $taxonomy_object->object_type, true ) ) {
foreach ( $taxonomy_object->object_type as $object_type ) {
$_object_type = get_post_type_object( $object_type );
// Grab the first one.
if ( ! empty( $_object_type->has_archive ) ) {
$posts_page = get_post_type_archive_link( $object_type );
break;
}
}
}
// Fallback for the 'All' link is the posts page.
if ( ! $posts_page ) {
if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_for_posts' ) ) {
$posts_page = get_permalink( get_option( 'page_for_posts' ) );
} else {
$posts_page = home_url( '/' );
}
}
$posts_page = esc_url( $posts_page );
if ( 'list' === $parsed_args['style'] ) {
$output .= "$show_option_all $show_option_all ";
}
}
if ( empty( $parsed_args['current_category'] ) && ( is_category() || is_tax() || is_tag() ) ) {
$current_term_object = get_queried_object();
if ( $current_term_object && $parsed_args['taxonomy'] === $current_term_object->taxonomy ) {
$parsed_args['current_category'] = get_queried_object_id();
}
}
if ( $parsed_args['hierarchical'] ) {
$depth = $parsed_args['depth'];
} else {
$depth = -1; // Flat.
}
$output .= walk_category_tree( $categories, $depth, $parsed_args );
}
if ( $parsed_args['title_li'] && 'list' === $parsed_args['style']
&& ( ! empty( $categories ) || ! $parsed_args['hide_title_if_empty'] )
) {
$output .= ' ';
}
/**
* Filters the HTML output of a taxonomy list.
*
* @since 2.1.0
*
* @param string $output HTML output.
* @param array|string $args An array or query string of taxonomy-listing arguments. See
* wp_list_categories() for information on accepted arguments.
*/
$html = apply_filters( 'wp_list_categories', $output, $args );
if ( $parsed_args['echo'] ) {
echo $html;
} else {
return $html;
}
}
/**
* Displays a tag cloud.
*
* Outputs a list of tags in what is called a 'tag cloud', where the size of each tag
* is determined by how many times that particular tag has been assigned to posts.
*
* @since 2.3.0
* @since 2.8.0 Added the `taxonomy` argument.
* @since 4.8.0 Added the `show_count` argument.
*
* @param array|string $args {
* Optional. Array or string of arguments for displaying a tag cloud. See wp_generate_tag_cloud()
* and get_terms() for the full lists of arguments that can be passed in `$args`.
*
* @type int $number The number of tags to display. Accepts any positive integer
* or zero to return all. Default 45.
* @type string $link Whether to display term editing links or term permalinks.
* Accepts 'edit' and 'view'. Default 'view'.
* @type string $post_type The post type. Used to highlight the proper post type menu
* on the linked edit page. Defaults to the first post type
* associated with the taxonomy.
* @type bool $echo Whether or not to echo the return value. Default true.
* }
* @return void|string|string[] Void if 'echo' argument is true, or on failure. Otherwise, tag cloud
* as a string or an array, depending on 'format' argument.
*/
function wp_tag_cloud( $args = '' ) {
$defaults = array(
'smallest' => 8,
'largest' => 22,
'unit' => 'pt',
'number' => 45,
'format' => 'flat',
'separator' => "\n",
'orderby' => 'name',
'order' => 'ASC',
'exclude' => '',
'include' => '',
'link' => 'view',
'taxonomy' => 'post_tag',
'post_type' => '',
'echo' => true,
'show_count' => 0,
);
$args = wp_parse_args( $args, $defaults );
$tags = get_terms(
array_merge(
$args,
array(
'orderby' => 'count',
'order' => 'DESC',
)
)
); // Always query top tags.
if ( empty( $tags ) || is_wp_error( $tags ) ) {
return;
}
foreach ( $tags as $key => $tag ) {
if ( 'edit' === $args['link'] ) {
$link = get_edit_term_link( $tag, $tag->taxonomy, $args['post_type'] );
} else {
$link = get_term_link( $tag, $tag->taxonomy );
}
if ( is_wp_error( $link ) ) {
return;
}
$tags[ $key ]->link = $link;
$tags[ $key ]->id = $tag->term_id;
}
// Here's where those top tags get sorted according to $args.
$return = wp_generate_tag_cloud( $tags, $args );
/**
* Filters the tag cloud output.
*
* @since 2.3.0
*
* @param string|string[] $return Tag cloud as a string or an array, depending on 'format' argument.
* @param array $args An array of tag cloud arguments. See wp_tag_cloud()
* for information on accepted arguments.
*/
$return = apply_filters( 'wp_tag_cloud', $return, $args );
if ( 'array' === $args['format'] || empty( $args['echo'] ) ) {
return $return;
}
echo $return;
}
/**
* Default topic count scaling for tag links.
*
* @since 2.9.0
*
* @param int $count Number of posts with that tag.
* @return int Scaled count.
*/
function default_topic_count_scale( $count ) {
return round( log10( $count + 1 ) * 100 );
}
/**
* Generates a tag cloud (heatmap) from provided data.
*
* @todo Complete functionality.
* @since 2.3.0
* @since 4.8.0 Added the `show_count` argument.
*
* @param WP_Term[] $tags Array of WP_Term objects to generate the tag cloud for.
* @param string|array $args {
* Optional. Array or string of arguments for generating a tag cloud.
*
* @type int $smallest Smallest font size used to display tags. Paired
* with the value of `$unit`, to determine CSS text
* size unit. Default 8 (pt).
* @type int $largest Largest font size used to display tags. Paired
* with the value of `$unit`, to determine CSS text
* size unit. Default 22 (pt).
* @type string $unit CSS text size unit to use with the `$smallest`
* and `$largest` values. Accepts any valid CSS text
* size unit. Default 'pt'.
* @type int $number The number of tags to return. Accepts any
* positive integer or zero to return all.
* Default 0.
* @type string $format Format to display the tag cloud in. Accepts 'flat'
* (tags separated with spaces), 'list' (tags displayed
* in an unordered list), or 'array' (returns an array).
* Default 'flat'.
* @type string $separator HTML or text to separate the tags. Default "\n" (newline).
* @type string $orderby Value to order tags by. Accepts 'name' or 'count'.
* Default 'name'. The {@see 'tag_cloud_sort'} filter
* can also affect how tags are sorted.
* @type string $order How to order the tags. Accepts 'ASC' (ascending),
* 'DESC' (descending), or 'RAND' (random). Default 'ASC'.
* @type int|bool $filter Whether to enable filtering of the final output
* via {@see 'wp_generate_tag_cloud'}. Default 1.
* @type array $topic_count_text Nooped plural text from _n_noop() to supply to
* tag counts. Default null.
* @type callable $topic_count_text_callback Callback used to generate nooped plural text for
* tag counts based on the count. Default null.
* @type callable $topic_count_scale_callback Callback used to determine the tag count scaling
* value. Default default_topic_count_scale().
* @type bool|int $show_count Whether to display the tag counts. Default 0. Accepts
* 0, 1, or their bool equivalents.
* }
* @return string|string[] Tag cloud as a string or an array, depending on 'format' argument.
*/
function wp_generate_tag_cloud( $tags, $args = '' ) {
$defaults = array(
'smallest' => 8,
'largest' => 22,
'unit' => 'pt',
'number' => 0,
'format' => 'flat',
'separator' => "\n",
'orderby' => 'name',
'order' => 'ASC',
'topic_count_text' => null,
'topic_count_text_callback' => null,
'topic_count_scale_callback' => 'default_topic_count_scale',
'filter' => 1,
'show_count' => 0,
);
$args = wp_parse_args( $args, $defaults );
$return = ( 'array' === $args['format'] ) ? array() : '';
if ( empty( $tags ) ) {
return $return;
}
// Juggle topic counts.
if ( isset( $args['topic_count_text'] ) ) {
// First look for nooped plural support via topic_count_text.
$translate_nooped_plural = $args['topic_count_text'];
} elseif ( ! empty( $args['topic_count_text_callback'] ) ) {
// Look for the alternative callback style. Ignore the previous default.
if ( 'default_topic_count_text' === $args['topic_count_text_callback'] ) {
/* translators: %s: Number of items (tags). */
$translate_nooped_plural = _n_noop( '%s item', '%s items' );
} else {
$translate_nooped_plural = false;
}
} elseif ( isset( $args['single_text'] ) && isset( $args['multiple_text'] ) ) {
// If no callback exists, look for the old-style single_text and multiple_text arguments.
// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralSingular,WordPress.WP.I18n.NonSingularStringLiteralPlural
$translate_nooped_plural = _n_noop( $args['single_text'], $args['multiple_text'] );
} else {
// This is the default for when no callback, plural, or argument is passed in.
/* translators: %s: Number of items (tags). */
$translate_nooped_plural = _n_noop( '%s item', '%s items' );
}
/**
* Filters how the items in a tag cloud are sorted.
*
* @since 2.8.0
*
* @param WP_Term[] $tags Ordered array of terms.
* @param array $args An array of tag cloud arguments.
*/
$tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
if ( empty( $tags_sorted ) ) {
return $return;
}
if ( $tags_sorted !== $tags ) {
$tags = $tags_sorted;
unset( $tags_sorted );
} else {
if ( 'RAND' === $args['order'] ) {
shuffle( $tags );
} else {
// SQL cannot save you; this is a second (potentially different) sort on a subset of data.
if ( 'name' === $args['orderby'] ) {
uasort( $tags, '_wp_object_name_sort_cb' );
} else {
uasort( $tags, '_wp_object_count_sort_cb' );
}
if ( 'DESC' === $args['order'] ) {
$tags = array_reverse( $tags, true );
}
}
}
if ( $args['number'] > 0 ) {
$tags = array_slice( $tags, 0, $args['number'] );
}
$counts = array();
$real_counts = array(); // For the alt tag.
foreach ( (array) $tags as $key => $tag ) {
$real_counts[ $key ] = $tag->count;
$counts[ $key ] = call_user_func( $args['topic_count_scale_callback'], $tag->count );
}
$min_count = min( $counts );
$spread = max( $counts ) - $min_count;
if ( $spread <= 0 ) {
$spread = 1;
}
$font_spread = $args['largest'] - $args['smallest'];
if ( $font_spread < 0 ) {
$font_spread = 1;
}
$font_step = $font_spread / $spread;
$aria_label = false;
/*
* Determine whether to output an 'aria-label' attribute with the tag name and count.
* When tags have a different font size, they visually convey an important information
* that should be available to assistive technologies too. On the other hand, sometimes
* themes set up the Tag Cloud to display all tags with the same font size (setting
* the 'smallest' and 'largest' arguments to the same value).
* In order to always serve the same content to all users, the 'aria-label' gets printed out:
* - when tags have a different size
* - when the tag count is displayed (for example when users check the checkbox in the
* Tag Cloud widget), regardless of the tags font size
*/
if ( $args['show_count'] || 0 !== $font_spread ) {
$aria_label = true;
}
// Assemble the data that will be used to generate the tag cloud markup.
$tags_data = array();
foreach ( $tags as $key => $tag ) {
$tag_id = isset( $tag->id ) ? $tag->id : $key;
$count = $counts[ $key ];
$real_count = $real_counts[ $key ];
if ( $translate_nooped_plural ) {
$formatted_count = sprintf( translate_nooped_plural( $translate_nooped_plural, $real_count ), number_format_i18n( $real_count ) );
} else {
$formatted_count = call_user_func( $args['topic_count_text_callback'], $real_count, $tag, $args );
}
$tags_data[] = array(
'id' => $tag_id,
'url' => ( '#' !== $tag->link ) ? $tag->link : '#',
'role' => ( '#' !== $tag->link ) ? '' : ' role="button"',
'name' => $tag->name,
'formatted_count' => $formatted_count,
'slug' => $tag->slug,
'real_count' => $real_count,
'class' => 'tag-cloud-link tag-link-' . $tag_id,
'font_size' => $args['smallest'] + ( $count - $min_count ) * $font_step,
'aria_label' => $aria_label ? sprintf( ' aria-label="%1$s (%2$s)"', esc_attr( $tag->name ), esc_attr( $formatted_count ) ) : '',
'show_count' => $args['show_count'] ? ' (' . $real_count . ') ' : '',
);
}
/**
* Filters the data used to generate the tag cloud.
*
* @since 4.3.0
*
* @param array[] $tags_data An array of term data arrays for terms used to generate the tag cloud.
*/
$tags_data = apply_filters( 'wp_generate_tag_cloud_data', $tags_data );
$a = array();
// Generate the output links array.
foreach ( $tags_data as $key => $tag_data ) {
$class = $tag_data['class'] . ' tag-link-position-' . ( $key + 1 );
$a[] = sprintf(
'%6$s%7$s ',
esc_url( $tag_data['url'] ),
$tag_data['role'],
esc_attr( $class ),
esc_attr( str_replace( ',', '.', $tag_data['font_size'] ) . $args['unit'] ),
$tag_data['aria_label'],
esc_html( $tag_data['name'] ),
$tag_data['show_count']
);
}
switch ( $args['format'] ) {
case 'array':
$return =& $a;
break;
case 'list':
/*
* Force role="list", as some browsers (sic: Safari 10) don't expose to assistive
* technologies the default role when the list is styled with `list-style: none`.
* Note: this is redundant but doesn't harm.
*/
$return = "\n\t";
$return .= implode( " \n\t", $a );
$return .= " \n \n";
break;
default:
$return = implode( $args['separator'], $a );
break;
}
if ( $args['filter'] ) {
/**
* Filters the generated output of a tag cloud.
*
* The filter is only evaluated if a true value is passed
* to the $filter argument in wp_generate_tag_cloud().
*
* @since 2.3.0
*
* @see wp_generate_tag_cloud()
*
* @param string[]|string $return String containing the generated HTML tag cloud output
* or an array of tag links if the 'format' argument
* equals 'array'.
* @param WP_Term[] $tags An array of terms used in the tag cloud.
* @param array $args An array of wp_generate_tag_cloud() arguments.
*/
return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
} else {
return $return;
}
}
/**
* Serves as a callback for comparing objects based on name.
*
* Used with `uasort()`.
*
* @since 3.1.0
* @access private
*
* @param object $a The first object to compare.
* @param object $b The second object to compare.
* @return int Negative number if `$a->name` is less than `$b->name`, zero if they are equal,
* or greater than zero if `$a->name` is greater than `$b->name`.
*/
function _wp_object_name_sort_cb( $a, $b ) {
return strnatcasecmp( $a->name, $b->name );
}
/**
* Serves as a callback for comparing objects based on count.
*
* Used with `uasort()`.
*
* @since 3.1.0
* @access private
*
* @param object $a The first object to compare.
* @param object $b The second object to compare.
* @return int Negative number if `$a->count` is less than `$b->count`, zero if they are equal,
* or greater than zero if `$a->count` is greater than `$b->count`.
*/
function _wp_object_count_sort_cb( $a, $b ) {
return ( $a->count - $b->count );
}
//
// Helper functions.
//
/**
* Retrieves HTML list content for category list.
*
* @since 2.1.0
* @since 5.3.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
* @uses Walker_Category to create HTML list content.
* @see Walker::walk() for parameters and return description.
*
* @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments.
* @return string
*/
function walk_category_tree( ...$args ) {
// The user's options are the third parameter.
if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
$walker = new Walker_Category();
} else {
/**
* @var Walker $walker
*/
$walker = $args[2]['walker'];
}
return $walker->walk( ...$args );
}
/**
* Retrieves HTML dropdown (select) content for category list.
*
* @since 2.1.0
* @since 5.3.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
* @uses Walker_CategoryDropdown to create HTML dropdown content.
* @see Walker::walk() for parameters and return description.
*
* @param mixed ...$args Elements array, maximum hierarchical depth and optional additional arguments.
* @return string
*/
function walk_category_dropdown_tree( ...$args ) {
// The user's options are the third parameter.
if ( empty( $args[2]['walker'] ) || ! ( $args[2]['walker'] instanceof Walker ) ) {
$walker = new Walker_CategoryDropdown();
} else {
/**
* @var Walker $walker
*/
$walker = $args[2]['walker'];
}
return $walker->walk( ...$args );
}
//
// Tags.
//
/**
* Retrieves the link to the tag.
*
* @since 2.3.0
*
* @see get_term_link()
*
* @param int|object $tag Tag ID or object.
* @return string Link on success, empty string if tag does not exist.
*/
function get_tag_link( $tag ) {
return get_category_link( $tag );
}
/**
* Retrieves the tags for a post.
*
* @since 2.3.0
*
* @param int|WP_Post $post Post ID or object.
* @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
function get_the_tags( $post = 0 ) {
$terms = get_the_terms( $post, 'post_tag' );
/**
* Filters the array of tags for the given post.
*
* @since 2.3.0
*
* @see get_the_terms()
*
* @param WP_Term[]|false|WP_Error $terms Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
return apply_filters( 'get_the_tags', $terms );
}
/**
* Retrieves the tags for a post formatted as a string.
*
* @since 2.3.0
*
* @param string $before Optional. String to use before the tags. Default empty.
* @param string $sep Optional. String to use between the tags. Default empty.
* @param string $after Optional. String to use after the tags. Default empty.
* @param int $post_id Optional. Post ID. Defaults to the current post ID.
* @return string|false|WP_Error A list of tags on success, false if there are no terms,
* WP_Error on failure.
*/
function get_the_tag_list( $before = '', $sep = '', $after = '', $post_id = 0 ) {
$tag_list = get_the_term_list( $post_id, 'post_tag', $before, $sep, $after );
/**
* Filters the tags list for a given post.
*
* @since 2.3.0
*
* @param string $tag_list List of tags.
* @param string $before String to use before the tags.
* @param string $sep String to use between the tags.
* @param string $after String to use after the tags.
* @param int $post_id Post ID.
*/
return apply_filters( 'the_tags', $tag_list, $before, $sep, $after, $post_id );
}
/**
* Displays the tags for a post.
*
* @since 2.3.0
*
* @param string $before Optional. String to use before the tags. Defaults to 'Tags:'.
* @param string $sep Optional. String to use between the tags. Default ', '.
* @param string $after Optional. String to use after the tags. Default empty.
*/
function the_tags( $before = null, $sep = ', ', $after = '' ) {
if ( null === $before ) {
$before = __( 'Tags: ' );
}
$the_tags = get_the_tag_list( $before, $sep, $after );
if ( ! is_wp_error( $the_tags ) ) {
echo $the_tags;
}
}
/**
* Retrieves tag description.
*
* @since 2.8.0
*
* @param int $tag Optional. Tag ID. Defaults to the current tag ID.
* @return string Tag description, if available.
*/
function tag_description( $tag = 0 ) {
return term_description( $tag );
}
/**
* Retrieves term description.
*
* @since 2.8.0
* @since 4.9.2 The `$taxonomy` parameter was deprecated.
*
* @param int $term Optional. Term ID. Defaults to the current term ID.
* @param null $deprecated Deprecated. Not used.
* @return string Term description, if available.
*/
function term_description( $term = 0, $deprecated = null ) {
if ( ! $term && ( is_tax() || is_tag() || is_category() ) ) {
$term = get_queried_object();
if ( $term ) {
$term = $term->term_id;
}
}
$description = get_term_field( 'description', $term );
return is_wp_error( $description ) ? '' : $description;
}
/**
* Retrieves the terms of the taxonomy that are attached to the post.
*
* @since 2.5.0
*
* @param int|WP_Post $post Post ID or object.
* @param string $taxonomy Taxonomy name.
* @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
* or the post does not exist, WP_Error on failure.
*/
function get_the_terms( $post, $taxonomy ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$terms = get_object_term_cache( $post->ID, $taxonomy );
if ( false === $terms ) {
$terms = wp_get_object_terms( $post->ID, $taxonomy );
if ( ! is_wp_error( $terms ) ) {
$term_ids = wp_list_pluck( $terms, 'term_id' );
wp_cache_add( $post->ID, $term_ids, $taxonomy . '_relationships' );
}
}
/**
* Filters the list of terms attached to the given post.
*
* @since 3.1.0
*
* @param WP_Term[]|WP_Error $terms Array of attached terms, or WP_Error on failure.
* @param int $post_id Post ID.
* @param string $taxonomy Name of the taxonomy.
*/
$terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
if ( empty( $terms ) ) {
return false;
}
return $terms;
}
/**
* Retrieves a post's terms as a list with specified format.
*
* Terms are linked to their respective term listing pages.
*
* @since 2.5.0
*
* @param int $post_id Post ID.
* @param string $taxonomy Taxonomy name.
* @param string $before Optional. String to use before the terms. Default empty.
* @param string $sep Optional. String to use between the terms. Default empty.
* @param string $after Optional. String to use after the terms. Default empty.
* @return string|false|WP_Error A list of terms on success, false if there are no terms,
* WP_Error on failure.
*/
function get_the_term_list( $post_id, $taxonomy, $before = '', $sep = '', $after = '' ) {
$terms = get_the_terms( $post_id, $taxonomy );
if ( is_wp_error( $terms ) ) {
return $terms;
}
if ( empty( $terms ) ) {
return false;
}
$links = array();
foreach ( $terms as $term ) {
$link = get_term_link( $term, $taxonomy );
if ( is_wp_error( $link ) ) {
return $link;
}
$links[] = '' . $term->name . ' ';
}
/**
* Filters the term links for a given taxonomy.
*
* The dynamic portion of the hook name, `$taxonomy`, refers
* to the taxonomy slug.
*
* Possible hook names include:
*
* - `term_links-category`
* - `term_links-post_tag`
* - `term_links-post_format`
*
* @since 2.5.0
*
* @param string[] $links An array of term links.
*/
$term_links = apply_filters( "term_links-{$taxonomy}", $links ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores
return $before . implode( $sep, $term_links ) . $after;
}
/**
* Retrieves term parents with separator.
*
* @since 4.8.0
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy name.
* @param string|array $args {
* Array of optional arguments.
*
* @type string $format Use term names or slugs for display. Accepts 'name' or 'slug'.
* Default 'name'.
* @type string $separator Separator for between the terms. Default '/'.
* @type bool $link Whether to format as a link. Default true.
* @type bool $inclusive Include the term to get the parents for. Default true.
* }
* @return string|WP_Error A list of term parents on success, WP_Error or empty string on failure.
*/
function get_term_parents_list( $term_id, $taxonomy, $args = array() ) {
$list = '';
$term = get_term( $term_id, $taxonomy );
if ( is_wp_error( $term ) ) {
return $term;
}
if ( ! $term ) {
return $list;
}
$term_id = $term->term_id;
$defaults = array(
'format' => 'name',
'separator' => '/',
'link' => true,
'inclusive' => true,
);
$args = wp_parse_args( $args, $defaults );
foreach ( array( 'link', 'inclusive' ) as $bool ) {
$args[ $bool ] = wp_validate_boolean( $args[ $bool ] );
}
$parents = get_ancestors( $term_id, $taxonomy, 'taxonomy' );
if ( $args['inclusive'] ) {
array_unshift( $parents, $term_id );
}
foreach ( array_reverse( $parents ) as $term_id ) {
$parent = get_term( $term_id, $taxonomy );
$name = ( 'slug' === $args['format'] ) ? $parent->slug : $parent->name;
if ( $args['link'] ) {
$list .= '' . $name . ' ' . $args['separator'];
} else {
$list .= $name . $args['separator'];
}
}
return $list;
}
/**
* Displays the terms for a post in a list.
*
* @since 2.5.0
*
* @param int $post_id Post ID.
* @param string $taxonomy Taxonomy name.
* @param string $before Optional. String to use before the terms. Default empty.
* @param string $sep Optional. String to use between the terms. Default ', '.
* @param string $after Optional. String to use after the terms. Default empty.
* @return void|false Void on success, false on failure.
*/
function the_terms( $post_id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
$term_list = get_the_term_list( $post_id, $taxonomy, $before, $sep, $after );
if ( is_wp_error( $term_list ) ) {
return false;
}
/**
* Filters the list of terms to display.
*
* @since 2.9.0
*
* @param string $term_list List of terms to display.
* @param string $taxonomy The taxonomy name.
* @param string $before String to use before the terms.
* @param string $sep String to use between the terms.
* @param string $after String to use after the terms.
*/
echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after );
}
/**
* Checks if the current post has any of given category.
*
* The given categories are checked against the post's categories' term_ids, names and slugs.
* Categories given as integers will only be checked against the post's categories' term_ids.
*
* If no categories are given, determines if post has any categories.
*
* @since 3.1.0
*
* @param string|int|array $category Optional. The category name/term_id/slug,
* or an array of them to check for. Default empty.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given categories
* (or any category, if no category specified). False otherwise.
*/
function has_category( $category = '', $post = null ) {
return has_term( $category, 'category', $post );
}
/**
* Checks if the current post has any of given tags.
*
* The given tags are checked against the post's tags' term_ids, names and slugs.
* Tags given as integers will only be checked against the post's tags' term_ids.
*
* If no tags are given, determines if post has any tags.
*
* For more information on this and similar theme functions, check out
* the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 2.6.0
* @since 2.7.0 Tags given as integers are only checked against
* the post's tags' term_ids, not names or slugs.
* @since 2.7.0 Can be used outside of the WordPress Loop if `$post` is provided.
*
* @param string|int|array $tag Optional. The tag name/term_id/slug,
* or an array of them to check for. Default empty.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given tags
* (or any tag, if no tag specified). False otherwise.
*/
function has_tag( $tag = '', $post = null ) {
return has_term( $tag, 'post_tag', $post );
}
/**
* Checks if the current post has any of given terms.
*
* The given terms are checked against the post's terms' term_ids, names and slugs.
* Terms given as integers will only be checked against the post's terms' term_ids.
*
* If no terms are given, determines if post has any terms.
*
* @since 3.1.0
*
* @param string|int|array $term Optional. The term name/term_id/slug,
* or an array of them to check for. Default empty.
* @param string $taxonomy Optional. Taxonomy name. Default empty.
* @param int|WP_Post $post Optional. Post to check. Defaults to the current post.
* @return bool True if the current post has any of the given terms
* (or any term, if no term specified). False otherwise.
*/
function has_term( $term = '', $taxonomy = '', $post = null ) {
$post = get_post( $post );
if ( ! $post ) {
return false;
}
$r = is_object_in_term( $post->ID, $taxonomy, $term );
if ( is_wp_error( $r ) ) {
return false;
}
return $r;
}
/**
* Comment API: WP_Comment_Query class
*
* @package WordPress
* @subpackage Comments
* @since 4.4.0
*/
/**
* Core class used for querying comments.
*
* @since 3.1.0
*
* @see WP_Comment_Query::__construct() for accepted arguments.
*/
#[AllowDynamicProperties]
class WP_Comment_Query {
/**
* SQL for database query.
*
* @since 4.0.1
* @var string
*/
public $request;
/**
* Metadata query container
*
* @since 3.5.0
* @var WP_Meta_Query A meta query instance.
*/
public $meta_query = false;
/**
* Metadata query clauses.
*
* @since 4.4.0
* @var array
*/
protected $meta_query_clauses;
/**
* SQL query clauses.
*
* @since 4.4.0
* @var array
*/
protected $sql_clauses = array(
'select' => '',
'from' => '',
'where' => array(),
'groupby' => '',
'orderby' => '',
'limits' => '',
);
/**
* SQL WHERE clause.
*
* Stored after the {@see 'comments_clauses'} filter is run on the compiled WHERE sub-clauses.
*
* @since 4.4.2
* @var string
*/
protected $filtered_where_clause;
/**
* Date query container
*
* @since 3.7.0
* @var WP_Date_Query A date query instance.
*/
public $date_query = false;
/**
* Query vars set by the user.
*
* @since 3.1.0
* @var array
*/
public $query_vars;
/**
* Default values for query vars.
*
* @since 4.2.0
* @var array
*/
public $query_var_defaults;
/**
* List of comments located by the query.
*
* @since 4.0.0
* @var int[]|WP_Comment[]
*/
public $comments;
/**
* The amount of found comments for the current query.
*
* @since 4.4.0
* @var int
*/
public $found_comments = 0;
/**
* The number of pages.
*
* @since 4.4.0
* @var int
*/
public $max_num_pages = 0;
/**
* Make private/protected methods readable for backward compatibility.
*
* @since 4.0.0
*
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @return mixed|false Return value of the callback, false otherwise.
*/
public function __call( $name, $arguments ) {
if ( 'get_search_sql' === $name ) {
return $this->get_search_sql( ...$arguments );
}
return false;
}
/**
* Constructor.
*
* Sets up the comment query, based on the query vars passed.
*
* @since 4.2.0
* @since 4.4.0 `$parent__in` and `$parent__not_in` were added.
* @since 4.4.0 Order by `comment__in` was added. `$update_comment_meta_cache`, `$no_found_rows`,
* `$hierarchical`, and `$update_comment_post_cache` were added.
* @since 4.5.0 Introduced the `$author_url` argument.
* @since 4.6.0 Introduced the `$cache_domain` argument.
* @since 4.9.0 Introduced the `$paged` argument.
* @since 5.1.0 Introduced the `$meta_compare_key` argument.
* @since 5.3.0 Introduced the `$meta_type_key` argument.
*
* @param string|array $query {
* Optional. Array or query string of comment query parameters. Default empty.
*
* @type string $author_email Comment author email address. Default empty.
* @type string $author_url Comment author URL. Default empty.
* @type int[] $author__in Array of author IDs to include comments for. Default empty.
* @type int[] $author__not_in Array of author IDs to exclude comments for. Default empty.
* @type int[] $comment__in Array of comment IDs to include. Default empty.
* @type int[] $comment__not_in Array of comment IDs to exclude. Default empty.
* @type bool $count Whether to return a comment count (true) or array of
* comment objects (false). Default false.
* @type array $date_query Date query clauses to limit comments by. See WP_Date_Query.
* Default null.
* @type string $fields Comment fields to return. Accepts 'ids' for comment IDs
* only or empty for all fields. Default empty.
* @type array $include_unapproved Array of IDs or email addresses of users whose unapproved
* comments will be returned by the query regardless of
* `$status`. Default empty.
* @type int $karma Karma score to retrieve matching comments for.
* Default empty.
* @type string|string[] $meta_key Meta key or keys to filter by.
* @type string|string[] $meta_value Meta value or values to filter by.
* @type string $meta_compare MySQL operator used for comparing the meta value.
* See WP_Meta_Query::__construct() for accepted values and default value.
* @type string $meta_compare_key MySQL operator used for comparing the meta key.
* See WP_Meta_Query::__construct() for accepted values and default value.
* @type string $meta_type MySQL data type that the meta_value column will be CAST to for comparisons.
* See WP_Meta_Query::__construct() for accepted values and default value.
* @type string $meta_type_key MySQL data type that the meta_key column will be CAST to for comparisons.
* See WP_Meta_Query::__construct() for accepted values and default value.
* @type array $meta_query An associative array of WP_Meta_Query arguments.
* See WP_Meta_Query::__construct() for accepted values.
* @type int $number Maximum number of comments to retrieve.
* Default empty (no limit).
* @type int $paged When used with `$number`, defines the page of results to return.
* When used with `$offset`, `$offset` takes precedence. Default 1.
* @type int $offset Number of comments to offset the query. Used to build
* LIMIT clause. Default 0.
* @type bool $no_found_rows Whether to disable the `SQL_CALC_FOUND_ROWS` query.
* Default: true.
* @type string|array $orderby Comment status or array of statuses. To use 'meta_value'
* or 'meta_value_num', `$meta_key` must also be defined.
* To sort by a specific `$meta_query` clause, use that
* clause's array key. Accepts:
* - 'comment_agent'
* - 'comment_approved'
* - 'comment_author'
* - 'comment_author_email'
* - 'comment_author_IP'
* - 'comment_author_url'
* - 'comment_content'
* - 'comment_date'
* - 'comment_date_gmt'
* - 'comment_ID'
* - 'comment_karma'
* - 'comment_parent'
* - 'comment_post_ID'
* - 'comment_type'
* - 'user_id'
* - 'comment__in'
* - 'meta_value'
* - 'meta_value_num'
* - The value of `$meta_key`
* - The array keys of `$meta_query`
* - false, an empty array, or 'none' to disable `ORDER BY` clause.
* Default: 'comment_date_gmt'.
* @type string $order How to order retrieved comments. Accepts 'ASC', 'DESC'.
* Default: 'DESC'.
* @type int $parent Parent ID of comment to retrieve children of.
* Default empty.
* @type int[] $parent__in Array of parent IDs of comments to retrieve children for.
* Default empty.
* @type int[] $parent__not_in Array of parent IDs of comments *not* to retrieve
* children for. Default empty.
* @type int[] $post_author__in Array of author IDs to retrieve comments for.
* Default empty.
* @type int[] $post_author__not_in Array of author IDs *not* to retrieve comments for.
* Default empty.
* @type int $post_id Limit results to those affiliated with a given post ID.
* Default 0.
* @type int[] $post__in Array of post IDs to include affiliated comments for.
* Default empty.
* @type int[] $post__not_in Array of post IDs to exclude affiliated comments for.
* Default empty.
* @type int $post_author Post author ID to limit results by. Default empty.
* @type string|string[] $post_status Post status or array of post statuses to retrieve
* affiliated comments for. Pass 'any' to match any value.
* Default empty.
* @type string|string[] $post_type Post type or array of post types to retrieve affiliated
* comments for. Pass 'any' to match any value. Default empty.
* @type string $post_name Post name to retrieve affiliated comments for.
* Default empty.
* @type int $post_parent Post parent ID to retrieve affiliated comments for.
* Default empty.
* @type string $search Search term(s) to retrieve matching comments for.
* Default empty.
* @type string|array $status Comment statuses to limit results by. Accepts an array
* or space/comma-separated list of 'hold' (`comment_status=0`),
* 'approve' (`comment_status=1`), 'all', or a custom
* comment status. Default 'all'.
* @type string|string[] $type Include comments of a given type, or array of types.
* Accepts 'comment', 'pings' (includes 'pingback' and
* 'trackback'), or any custom type string. Default empty.
* @type string[] $type__in Include comments from a given array of comment types.
* Default empty.
* @type string[] $type__not_in Exclude comments from a given array of comment types.
* Default empty.
* @type int $user_id Include comments for a specific user ID. Default empty.
* @type bool|string $hierarchical Whether to include comment descendants in the results.
* - 'threaded' returns a tree, with each comment's children
* stored in a `children` property on the `WP_Comment` object.
* - 'flat' returns a flat array of found comments plus
* their children.
* - Boolean `false` leaves out descendants.
* The parameter is ignored (forced to `false`) when
* `$fields` is 'ids' or 'counts'. Accepts 'threaded',
* 'flat', or false. Default: false.
* @type string $cache_domain Unique cache key to be produced when this query is stored in
* an object cache. Default is 'core'.
* @type bool $update_comment_meta_cache Whether to prime the metadata cache for found comments.
* Default true.
* @type bool $update_comment_post_cache Whether to prime the cache for comment posts.
* Default false.
* }
*/
public function __construct( $query = '' ) {
$this->query_var_defaults = array(
'author_email' => '',
'author_url' => '',
'author__in' => '',
'author__not_in' => '',
'include_unapproved' => '',
'fields' => '',
'ID' => '',
'comment__in' => '',
'comment__not_in' => '',
'karma' => '',
'number' => '',
'offset' => '',
'no_found_rows' => true,
'orderby' => '',
'order' => 'DESC',
'paged' => 1,
'parent' => '',
'parent__in' => '',
'parent__not_in' => '',
'post_author__in' => '',
'post_author__not_in' => '',
'post_ID' => '',
'post_id' => 0,
'post__in' => '',
'post__not_in' => '',
'post_author' => '',
'post_name' => '',
'post_parent' => '',
'post_status' => '',
'post_type' => '',
'status' => 'all',
'type' => '',
'type__in' => '',
'type__not_in' => '',
'user_id' => '',
'search' => '',
'count' => false,
'meta_key' => '',
'meta_value' => '',
'meta_query' => '',
'date_query' => null, // See WP_Date_Query.
'hierarchical' => false,
'cache_domain' => 'core',
'update_comment_meta_cache' => true,
'update_comment_post_cache' => false,
);
if ( ! empty( $query ) ) {
$this->query( $query );
}
}
/**
* Parse arguments passed to the comment query with default query parameters.
*
* @since 4.2.0 Extracted from WP_Comment_Query::query().
*
* @param string|array $query WP_Comment_Query arguments. See WP_Comment_Query::__construct() for accepted arguments.
*/
public function parse_query( $query = '' ) {
if ( empty( $query ) ) {
$query = $this->query_vars;
}
$this->query_vars = wp_parse_args( $query, $this->query_var_defaults );
/**
* Fires after the comment query vars have been parsed.
*
* @since 4.2.0
*
* @param WP_Comment_Query $query The WP_Comment_Query instance (passed by reference).
*/
do_action_ref_array( 'parse_comment_query', array( &$this ) );
}
/**
* Sets up the WordPress query for retrieving comments.
*
* @since 3.1.0
* @since 4.1.0 Introduced 'comment__in', 'comment__not_in', 'post_author__in',
* 'post_author__not_in', 'author__in', 'author__not_in', 'post__in',
* 'post__not_in', 'include_unapproved', 'type__in', and 'type__not_in'
* arguments to $query_vars.
* @since 4.2.0 Moved parsing to WP_Comment_Query::parse_query().
*
* @param string|array $query Array or URL query string of parameters.
* @return array|int List of comments, or number of comments when 'count' is passed as a query var.
*/
public function query( $query ) {
$this->query_vars = wp_parse_args( $query );
return $this->get_comments();
}
/**
* Get a list of comments matching the query vars.
*
* @since 4.2.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @return int|int[]|WP_Comment[] List of comments or number of found comments if `$count` argument is true.
*/
public function get_comments() {
global $wpdb;
$this->parse_query();
// Parse meta query.
$this->meta_query = new WP_Meta_Query();
$this->meta_query->parse_query_vars( $this->query_vars );
/**
* Fires before comments are retrieved.
*
* @since 3.1.0
*
* @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference).
*/
do_action_ref_array( 'pre_get_comments', array( &$this ) );
// Reparse query vars, in case they were modified in a 'pre_get_comments' callback.
$this->meta_query->parse_query_vars( $this->query_vars );
if ( ! empty( $this->meta_query->queries ) ) {
$this->meta_query_clauses = $this->meta_query->get_sql( 'comment', $wpdb->comments, 'comment_ID', $this );
}
$comment_data = null;
/**
* Filters the comments data before the query takes place.
*
* Return a non-null value to bypass WordPress' default comment queries.
*
* The expected return type from this filter depends on the value passed
* in the request query vars:
* - When `$this->query_vars['count']` is set, the filter should return
* the comment count as an integer.
* - When `'ids' === $this->query_vars['fields']`, the filter should return
* an array of comment IDs.
* - Otherwise the filter should return an array of WP_Comment objects.
*
* Note that if the filter returns an array of comment data, it will be assigned
* to the `comments` property of the current WP_Comment_Query instance.
*
* Filtering functions that require pagination information are encouraged to set
* the `found_comments` and `max_num_pages` properties of the WP_Comment_Query object,
* passed to the filter by reference. If WP_Comment_Query does not perform a database
* query, it will not have enough information to generate these values itself.
*
* @since 5.3.0
* @since 5.6.0 The returned array of comment data is assigned to the `comments` property
* of the current WP_Comment_Query instance.
*
* @param array|int|null $comment_data Return an array of comment data to short-circuit WP's comment query,
* the comment count as an integer if `$this->query_vars['count']` is set,
* or null to allow WP to run its normal queries.
* @param WP_Comment_Query $query The WP_Comment_Query instance, passed by reference.
*/
$comment_data = apply_filters_ref_array( 'comments_pre_query', array( $comment_data, &$this ) );
if ( null !== $comment_data ) {
if ( is_array( $comment_data ) && ! $this->query_vars['count'] ) {
$this->comments = $comment_data;
}
return $comment_data;
}
/*
* Only use the args defined in the query_var_defaults to compute the key,
* but ignore 'fields', 'update_comment_meta_cache', 'update_comment_post_cache' which does not affect query results.
*/
$_args = wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) );
unset( $_args['fields'], $_args['update_comment_meta_cache'], $_args['update_comment_post_cache'] );
$key = md5( serialize( $_args ) );
$last_changed = wp_cache_get_last_changed( 'comment' );
$cache_key = "get_comments:$key:$last_changed";
$cache_value = wp_cache_get( $cache_key, 'comment-queries' );
if ( false === $cache_value ) {
$comment_ids = $this->get_comment_ids();
if ( $comment_ids ) {
$this->set_found_comments();
}
$cache_value = array(
'comment_ids' => $comment_ids,
'found_comments' => $this->found_comments,
);
wp_cache_add( $cache_key, $cache_value, 'comment-queries' );
} else {
$comment_ids = $cache_value['comment_ids'];
$this->found_comments = $cache_value['found_comments'];
}
if ( $this->found_comments && $this->query_vars['number'] ) {
$this->max_num_pages = (int) ceil( $this->found_comments / $this->query_vars['number'] );
}
// If querying for a count only, there's nothing more to do.
if ( $this->query_vars['count'] ) {
// $comment_ids is actually a count in this case.
return (int) $comment_ids;
}
$comment_ids = array_map( 'intval', $comment_ids );
if ( $this->query_vars['update_comment_meta_cache'] ) {
wp_lazyload_comment_meta( $comment_ids );
}
if ( 'ids' === $this->query_vars['fields'] ) {
$this->comments = $comment_ids;
return $this->comments;
}
_prime_comment_caches( $comment_ids, false );
// Fetch full comment objects from the primed cache.
$_comments = array();
foreach ( $comment_ids as $comment_id ) {
$_comment = get_comment( $comment_id );
if ( $_comment ) {
$_comments[] = $_comment;
}
}
// Prime comment post caches.
if ( $this->query_vars['update_comment_post_cache'] ) {
$comment_post_ids = array();
foreach ( $_comments as $_comment ) {
$comment_post_ids[] = $_comment->comment_post_ID;
}
_prime_post_caches( $comment_post_ids, false, false );
}
/**
* Filters the comment query results.
*
* @since 3.1.0
*
* @param WP_Comment[] $_comments An array of comments.
* @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference).
*/
$_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) );
// Convert to WP_Comment instances.
$comments = array_map( 'get_comment', $_comments );
if ( $this->query_vars['hierarchical'] ) {
$comments = $this->fill_descendants( $comments );
}
$this->comments = $comments;
return $this->comments;
}
/**
* Used internally to get a list of comment IDs matching the query vars.
*
* @since 4.4.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @return int|array A single count of comment IDs if a count query. An array of comment IDs if a full query.
*/
protected function get_comment_ids() {
global $wpdb;
// Assemble clauses related to 'comment_approved'.
$approved_clauses = array();
// 'status' accepts an array or a comma-separated string.
$status_clauses = array();
$statuses = wp_parse_list( $this->query_vars['status'] );
// Empty 'status' should be interpreted as 'all'.
if ( empty( $statuses ) ) {
$statuses = array( 'all' );
}
// 'any' overrides other statuses.
if ( ! in_array( 'any', $statuses, true ) ) {
foreach ( $statuses as $status ) {
switch ( $status ) {
case 'hold':
$status_clauses[] = "comment_approved = '0'";
break;
case 'approve':
$status_clauses[] = "comment_approved = '1'";
break;
case 'all':
case '':
$status_clauses[] = "( comment_approved = '0' OR comment_approved = '1' )";
break;
default:
$status_clauses[] = $wpdb->prepare( 'comment_approved = %s', $status );
break;
}
}
if ( ! empty( $status_clauses ) ) {
$approved_clauses[] = '( ' . implode( ' OR ', $status_clauses ) . ' )';
}
}
// User IDs or emails whose unapproved comments are included, regardless of $status.
if ( ! empty( $this->query_vars['include_unapproved'] ) ) {
$include_unapproved = wp_parse_list( $this->query_vars['include_unapproved'] );
foreach ( $include_unapproved as $unapproved_identifier ) {
// Numeric values are assumed to be user IDs.
if ( is_numeric( $unapproved_identifier ) ) {
$approved_clauses[] = $wpdb->prepare( "( user_id = %d AND comment_approved = '0' )", $unapproved_identifier );
} else {
// Otherwise we match against email addresses.
if ( ! empty( $_GET['unapproved'] ) && ! empty( $_GET['moderation-hash'] ) ) {
// Only include requested comment.
$approved_clauses[] = $wpdb->prepare( "( comment_author_email = %s AND comment_approved = '0' AND {$wpdb->comments}.comment_ID = %d )", $unapproved_identifier, (int) $_GET['unapproved'] );
} else {
// Include all of the author's unapproved comments.
$approved_clauses[] = $wpdb->prepare( "( comment_author_email = %s AND comment_approved = '0' )", $unapproved_identifier );
}
}
}
}
// Collapse comment_approved clauses into a single OR-separated clause.
if ( ! empty( $approved_clauses ) ) {
if ( 1 === count( $approved_clauses ) ) {
$this->sql_clauses['where']['approved'] = $approved_clauses[0];
} else {
$this->sql_clauses['where']['approved'] = '( ' . implode( ' OR ', $approved_clauses ) . ' )';
}
}
$order = ( 'ASC' === strtoupper( $this->query_vars['order'] ) ) ? 'ASC' : 'DESC';
// Disable ORDER BY with 'none', an empty array, or boolean false.
if ( in_array( $this->query_vars['orderby'], array( 'none', array(), false ), true ) ) {
$orderby = '';
} elseif ( ! empty( $this->query_vars['orderby'] ) ) {
$ordersby = is_array( $this->query_vars['orderby'] ) ?
$this->query_vars['orderby'] :
preg_split( '/[,\s]/', $this->query_vars['orderby'] );
$orderby_array = array();
$found_orderby_comment_id = false;
foreach ( $ordersby as $_key => $_value ) {
if ( ! $_value ) {
continue;
}
if ( is_int( $_key ) ) {
$_orderby = $_value;
$_order = $order;
} else {
$_orderby = $_key;
$_order = $_value;
}
if ( ! $found_orderby_comment_id && in_array( $_orderby, array( 'comment_ID', 'comment__in' ), true ) ) {
$found_orderby_comment_id = true;
}
$parsed = $this->parse_orderby( $_orderby );
if ( ! $parsed ) {
continue;
}
if ( 'comment__in' === $_orderby ) {
$orderby_array[] = $parsed;
continue;
}
$orderby_array[] = $parsed . ' ' . $this->parse_order( $_order );
}
// If no valid clauses were found, order by comment_date_gmt.
if ( empty( $orderby_array ) ) {
$orderby_array[] = "$wpdb->comments.comment_date_gmt $order";
}
// To ensure determinate sorting, always include a comment_ID clause.
if ( ! $found_orderby_comment_id ) {
$comment_id_order = '';
// Inherit order from comment_date or comment_date_gmt, if available.
foreach ( $orderby_array as $orderby_clause ) {
if ( preg_match( '/comment_date(?:_gmt)*\ (ASC|DESC)/', $orderby_clause, $match ) ) {
$comment_id_order = $match[1];
break;
}
}
// If no date-related order is available, use the date from the first available clause.
if ( ! $comment_id_order ) {
foreach ( $orderby_array as $orderby_clause ) {
if ( str_contains( 'ASC', $orderby_clause ) ) {
$comment_id_order = 'ASC';
} else {
$comment_id_order = 'DESC';
}
break;
}
}
// Default to DESC.
if ( ! $comment_id_order ) {
$comment_id_order = 'DESC';
}
$orderby_array[] = "$wpdb->comments.comment_ID $comment_id_order";
}
$orderby = implode( ', ', $orderby_array );
} else {
$orderby = "$wpdb->comments.comment_date_gmt $order";
}
$number = absint( $this->query_vars['number'] );
$offset = absint( $this->query_vars['offset'] );
$paged = absint( $this->query_vars['paged'] );
$limits = '';
if ( ! empty( $number ) ) {
if ( $offset ) {
$limits = 'LIMIT ' . $offset . ',' . $number;
} else {
$limits = 'LIMIT ' . ( $number * ( $paged - 1 ) ) . ',' . $number;
}
}
if ( $this->query_vars['count'] ) {
$fields = 'COUNT(*)';
} else {
$fields = "$wpdb->comments.comment_ID";
}
$post_id = absint( $this->query_vars['post_id'] );
if ( ! empty( $post_id ) ) {
$this->sql_clauses['where']['post_id'] = $wpdb->prepare( 'comment_post_ID = %d', $post_id );
}
// Parse comment IDs for an IN clause.
if ( ! empty( $this->query_vars['comment__in'] ) ) {
$this->sql_clauses['where']['comment__in'] = "$wpdb->comments.comment_ID IN ( " . implode( ',', wp_parse_id_list( $this->query_vars['comment__in'] ) ) . ' )';
}
// Parse comment IDs for a NOT IN clause.
if ( ! empty( $this->query_vars['comment__not_in'] ) ) {
$this->sql_clauses['where']['comment__not_in'] = "$wpdb->comments.comment_ID NOT IN ( " . implode( ',', wp_parse_id_list( $this->query_vars['comment__not_in'] ) ) . ' )';
}
// Parse comment parent IDs for an IN clause.
if ( ! empty( $this->query_vars['parent__in'] ) ) {
$this->sql_clauses['where']['parent__in'] = 'comment_parent IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['parent__in'] ) ) . ' )';
}
// Parse comment parent IDs for a NOT IN clause.
if ( ! empty( $this->query_vars['parent__not_in'] ) ) {
$this->sql_clauses['where']['parent__not_in'] = 'comment_parent NOT IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['parent__not_in'] ) ) . ' )';
}
// Parse comment post IDs for an IN clause.
if ( ! empty( $this->query_vars['post__in'] ) ) {
$this->sql_clauses['where']['post__in'] = 'comment_post_ID IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['post__in'] ) ) . ' )';
}
// Parse comment post IDs for a NOT IN clause.
if ( ! empty( $this->query_vars['post__not_in'] ) ) {
$this->sql_clauses['where']['post__not_in'] = 'comment_post_ID NOT IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['post__not_in'] ) ) . ' )';
}
if ( '' !== $this->query_vars['author_email'] ) {
$this->sql_clauses['where']['author_email'] = $wpdb->prepare( 'comment_author_email = %s', $this->query_vars['author_email'] );
}
if ( '' !== $this->query_vars['author_url'] ) {
$this->sql_clauses['where']['author_url'] = $wpdb->prepare( 'comment_author_url = %s', $this->query_vars['author_url'] );
}
if ( '' !== $this->query_vars['karma'] ) {
$this->sql_clauses['where']['karma'] = $wpdb->prepare( 'comment_karma = %d', $this->query_vars['karma'] );
}
// Filtering by comment_type: 'type', 'type__in', 'type__not_in'.
$raw_types = array(
'IN' => array_merge( (array) $this->query_vars['type'], (array) $this->query_vars['type__in'] ),
'NOT IN' => (array) $this->query_vars['type__not_in'],
);
$comment_types = array();
foreach ( $raw_types as $operator => $_raw_types ) {
$_raw_types = array_unique( $_raw_types );
foreach ( $_raw_types as $type ) {
switch ( $type ) {
// An empty translates to 'all', for backward compatibility.
case '':
case 'all':
break;
case 'comment':
case 'comments':
$comment_types[ $operator ][] = "''";
$comment_types[ $operator ][] = "'comment'";
break;
case 'pings':
$comment_types[ $operator ][] = "'pingback'";
$comment_types[ $operator ][] = "'trackback'";
break;
default:
$comment_types[ $operator ][] = $wpdb->prepare( '%s', $type );
break;
}
}
if ( ! empty( $comment_types[ $operator ] ) ) {
$types_sql = implode( ', ', $comment_types[ $operator ] );
$this->sql_clauses['where'][ 'comment_type__' . strtolower( str_replace( ' ', '_', $operator ) ) ] = "comment_type $operator ($types_sql)";
}
}
$parent = $this->query_vars['parent'];
if ( $this->query_vars['hierarchical'] && ! $parent ) {
$parent = 0;
}
if ( '' !== $parent ) {
$this->sql_clauses['where']['parent'] = $wpdb->prepare( 'comment_parent = %d', $parent );
}
if ( is_array( $this->query_vars['user_id'] ) ) {
$this->sql_clauses['where']['user_id'] = 'user_id IN (' . implode( ',', array_map( 'absint', $this->query_vars['user_id'] ) ) . ')';
} elseif ( '' !== $this->query_vars['user_id'] ) {
$this->sql_clauses['where']['user_id'] = $wpdb->prepare( 'user_id = %d', $this->query_vars['user_id'] );
}
// Falsey search strings are ignored.
if ( isset( $this->query_vars['search'] ) && strlen( $this->query_vars['search'] ) ) {
$search_sql = $this->get_search_sql(
$this->query_vars['search'],
array( 'comment_author', 'comment_author_email', 'comment_author_url', 'comment_author_IP', 'comment_content' )
);
// Strip leading 'AND'.
$this->sql_clauses['where']['search'] = preg_replace( '/^\s*AND\s*/', '', $search_sql );
}
// If any post-related query vars are passed, join the posts table.
$join_posts_table = false;
$plucked = wp_array_slice_assoc( $this->query_vars, array( 'post_author', 'post_name', 'post_parent' ) );
$post_fields = array_filter( $plucked );
if ( ! empty( $post_fields ) ) {
$join_posts_table = true;
foreach ( $post_fields as $field_name => $field_value ) {
// $field_value may be an array.
$esses = array_fill( 0, count( (array) $field_value ), '%s' );
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
$this->sql_clauses['where'][ $field_name ] = $wpdb->prepare( " {$wpdb->posts}.{$field_name} IN (" . implode( ',', $esses ) . ')', $field_value );
}
}
// 'post_status' and 'post_type' are handled separately, due to the specialized behavior of 'any'.
foreach ( array( 'post_status', 'post_type' ) as $field_name ) {
$q_values = array();
if ( ! empty( $this->query_vars[ $field_name ] ) ) {
$q_values = $this->query_vars[ $field_name ];
if ( ! is_array( $q_values ) ) {
$q_values = explode( ',', $q_values );
}
// 'any' will cause the query var to be ignored.
if ( in_array( 'any', $q_values, true ) || empty( $q_values ) ) {
continue;
}
$join_posts_table = true;
$esses = array_fill( 0, count( $q_values ), '%s' );
// phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
$this->sql_clauses['where'][ $field_name ] = $wpdb->prepare( " {$wpdb->posts}.{$field_name} IN (" . implode( ',', $esses ) . ')', $q_values );
}
}
// Comment author IDs for an IN clause.
if ( ! empty( $this->query_vars['author__in'] ) ) {
$this->sql_clauses['where']['author__in'] = 'user_id IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['author__in'] ) ) . ' )';
}
// Comment author IDs for a NOT IN clause.
if ( ! empty( $this->query_vars['author__not_in'] ) ) {
$this->sql_clauses['where']['author__not_in'] = 'user_id NOT IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['author__not_in'] ) ) . ' )';
}
// Post author IDs for an IN clause.
if ( ! empty( $this->query_vars['post_author__in'] ) ) {
$join_posts_table = true;
$this->sql_clauses['where']['post_author__in'] = 'post_author IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['post_author__in'] ) ) . ' )';
}
// Post author IDs for a NOT IN clause.
if ( ! empty( $this->query_vars['post_author__not_in'] ) ) {
$join_posts_table = true;
$this->sql_clauses['where']['post_author__not_in'] = 'post_author NOT IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['post_author__not_in'] ) ) . ' )';
}
$join = '';
$groupby = '';
if ( $join_posts_table ) {
$join .= "JOIN $wpdb->posts ON $wpdb->posts.ID = $wpdb->comments.comment_post_ID";
}
if ( ! empty( $this->meta_query_clauses ) ) {
$join .= $this->meta_query_clauses['join'];
// Strip leading 'AND'.
$this->sql_clauses['where']['meta_query'] = preg_replace( '/^\s*AND\s*/', '', $this->meta_query_clauses['where'] );
if ( ! $this->query_vars['count'] ) {
$groupby = "{$wpdb->comments}.comment_ID";
}
}
if ( ! empty( $this->query_vars['date_query'] ) && is_array( $this->query_vars['date_query'] ) ) {
$this->date_query = new WP_Date_Query( $this->query_vars['date_query'], 'comment_date' );
// Strip leading 'AND'.
$this->sql_clauses['where']['date_query'] = preg_replace( '/^\s*AND\s*/', '', $this->date_query->get_sql() );
}
$where = implode( ' AND ', $this->sql_clauses['where'] );
$pieces = array( 'fields', 'join', 'where', 'orderby', 'limits', 'groupby' );
/**
* Filters the comment query clauses.
*
* @since 3.1.0
*
* @param string[] $clauses {
* Associative array of the clauses for the query.
*
* @type string $fields The SELECT clause of the query.
* @type string $join The JOIN clause of the query.
* @type string $where The WHERE clause of the query.
* @type string $orderby The ORDER BY clause of the query.
* @type string $limits The LIMIT clause of the query.
* @type string $groupby The GROUP BY clause of the query.
* }
* @param WP_Comment_Query $query Current instance of WP_Comment_Query (passed by reference).
*/
$clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
$fields = isset( $clauses['fields'] ) ? $clauses['fields'] : '';
$join = isset( $clauses['join'] ) ? $clauses['join'] : '';
$where = isset( $clauses['where'] ) ? $clauses['where'] : '';
$orderby = isset( $clauses['orderby'] ) ? $clauses['orderby'] : '';
$limits = isset( $clauses['limits'] ) ? $clauses['limits'] : '';
$groupby = isset( $clauses['groupby'] ) ? $clauses['groupby'] : '';
$this->filtered_where_clause = $where;
if ( $where ) {
$where = 'WHERE ' . $where;
}
if ( $groupby ) {
$groupby = 'GROUP BY ' . $groupby;
}
if ( $orderby ) {
$orderby = "ORDER BY $orderby";
}
$found_rows = '';
if ( ! $this->query_vars['no_found_rows'] ) {
$found_rows = 'SQL_CALC_FOUND_ROWS';
}
$this->sql_clauses['select'] = "SELECT $found_rows $fields";
$this->sql_clauses['from'] = "FROM $wpdb->comments $join";
$this->sql_clauses['groupby'] = $groupby;
$this->sql_clauses['orderby'] = $orderby;
$this->sql_clauses['limits'] = $limits;
// Beginning of the string is on a new line to prevent leading whitespace. See https://core.trac.wordpress.org/ticket/56841.
$this->request =
"{$this->sql_clauses['select']}
{$this->sql_clauses['from']}
{$where}
{$this->sql_clauses['groupby']}
{$this->sql_clauses['orderby']}
{$this->sql_clauses['limits']}";
if ( $this->query_vars['count'] ) {
return (int) $wpdb->get_var( $this->request );
} else {
$comment_ids = $wpdb->get_col( $this->request );
return array_map( 'intval', $comment_ids );
}
}
/**
* Populates found_comments and max_num_pages properties for the current
* query if the limit clause was used.
*
* @since 4.6.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*/
private function set_found_comments() {
global $wpdb;
if ( $this->query_vars['number'] && ! $this->query_vars['no_found_rows'] ) {
/**
* Filters the query used to retrieve found comment count.
*
* @since 4.4.0
*
* @param string $found_comments_query SQL query. Default 'SELECT FOUND_ROWS()'.
* @param WP_Comment_Query $comment_query The `WP_Comment_Query` instance.
*/
$found_comments_query = apply_filters( 'found_comments_query', 'SELECT FOUND_ROWS()', $this );
$this->found_comments = (int) $wpdb->get_var( $found_comments_query );
}
}
/**
* Fetch descendants for located comments.
*
* Instead of calling `get_children()` separately on each child comment, we do a single set of queries to fetch
* the descendant trees for all matched top-level comments.
*
* @since 4.4.0
*
* @param WP_Comment[] $comments Array of top-level comments whose descendants should be filled in.
* @return array
*/
protected function fill_descendants( $comments ) {
$levels = array(
0 => wp_list_pluck( $comments, 'comment_ID' ),
);
$key = md5( serialize( wp_array_slice_assoc( $this->query_vars, array_keys( $this->query_var_defaults ) ) ) );
$last_changed = wp_cache_get_last_changed( 'comment' );
// Fetch an entire level of the descendant tree at a time.
$level = 0;
$exclude_keys = array( 'parent', 'parent__in', 'parent__not_in' );
do {
// Parent-child relationships may be cached. Only query for those that are not.
$child_ids = array();
$uncached_parent_ids = array();
$_parent_ids = $levels[ $level ];
if ( $_parent_ids ) {
$cache_keys = array();
foreach ( $_parent_ids as $parent_id ) {
$cache_keys[ $parent_id ] = "get_comment_child_ids:$parent_id:$key:$last_changed";
}
$cache_data = wp_cache_get_multiple( array_values( $cache_keys ), 'comment-queries' );
foreach ( $_parent_ids as $parent_id ) {
$parent_child_ids = $cache_data[ $cache_keys[ $parent_id ] ];
if ( false !== $parent_child_ids ) {
$child_ids = array_merge( $child_ids, $parent_child_ids );
} else {
$uncached_parent_ids[] = $parent_id;
}
}
}
if ( $uncached_parent_ids ) {
// Fetch this level of comments.
$parent_query_args = $this->query_vars;
foreach ( $exclude_keys as $exclude_key ) {
$parent_query_args[ $exclude_key ] = '';
}
$parent_query_args['parent__in'] = $uncached_parent_ids;
$parent_query_args['no_found_rows'] = true;
$parent_query_args['hierarchical'] = false;
$parent_query_args['offset'] = 0;
$parent_query_args['number'] = 0;
$level_comments = get_comments( $parent_query_args );
// Cache parent-child relationships.
$parent_map = array_fill_keys( $uncached_parent_ids, array() );
foreach ( $level_comments as $level_comment ) {
$parent_map[ $level_comment->comment_parent ][] = $level_comment->comment_ID;
$child_ids[] = $level_comment->comment_ID;
}
$data = array();
foreach ( $parent_map as $parent_id => $children ) {
$cache_key = "get_comment_child_ids:$parent_id:$key:$last_changed";
$data[ $cache_key ] = $children;
}
wp_cache_set_multiple( $data, 'comment-queries' );
}
++$level;
$levels[ $level ] = $child_ids;
} while ( $child_ids );
// Prime comment caches for non-top-level comments.
$descendant_ids = array();
for ( $i = 1, $c = count( $levels ); $i < $c; $i++ ) {
$descendant_ids = array_merge( $descendant_ids, $levels[ $i ] );
}
_prime_comment_caches( $descendant_ids, $this->query_vars['update_comment_meta_cache'] );
// Assemble a flat array of all comments + descendants.
$all_comments = $comments;
foreach ( $descendant_ids as $descendant_id ) {
$all_comments[] = get_comment( $descendant_id );
}
// If a threaded representation was requested, build the tree.
if ( 'threaded' === $this->query_vars['hierarchical'] ) {
$threaded_comments = array();
$ref = array();
foreach ( $all_comments as $k => $c ) {
$_c = get_comment( $c->comment_ID );
// If the comment isn't in the reference array, it goes in the top level of the thread.
if ( ! isset( $ref[ $c->comment_parent ] ) ) {
$threaded_comments[ $_c->comment_ID ] = $_c;
$ref[ $_c->comment_ID ] = $threaded_comments[ $_c->comment_ID ];
// Otherwise, set it as a child of its parent.
} else {
$ref[ $_c->comment_parent ]->add_child( $_c );
$ref[ $_c->comment_ID ] = $ref[ $_c->comment_parent ]->get_child( $_c->comment_ID );
}
}
// Set the 'populated_children' flag, to ensure additional database queries aren't run.
foreach ( $ref as $_ref ) {
$_ref->populated_children( true );
}
$comments = $threaded_comments;
} else {
$comments = $all_comments;
}
return $comments;
}
/**
* Used internally to generate an SQL string for searching across multiple columns.
*
* @since 3.1.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $search Search string.
* @param string[] $columns Array of columns to search.
* @return string Search SQL.
*/
protected function get_search_sql( $search, $columns ) {
global $wpdb;
$like = '%' . $wpdb->esc_like( $search ) . '%';
$searches = array();
foreach ( $columns as $column ) {
$searches[] = $wpdb->prepare( "$column LIKE %s", $like );
}
return ' AND (' . implode( ' OR ', $searches ) . ')';
}
/**
* Parse and sanitize 'orderby' keys passed to the comment query.
*
* @since 4.2.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $orderby Alias for the field to order by.
* @return string|false Value to used in the ORDER clause. False otherwise.
*/
protected function parse_orderby( $orderby ) {
global $wpdb;
$allowed_keys = array(
'comment_agent',
'comment_approved',
'comment_author',
'comment_author_email',
'comment_author_IP',
'comment_author_url',
'comment_content',
'comment_date',
'comment_date_gmt',
'comment_ID',
'comment_karma',
'comment_parent',
'comment_post_ID',
'comment_type',
'user_id',
);
if ( ! empty( $this->query_vars['meta_key'] ) ) {
$allowed_keys[] = $this->query_vars['meta_key'];
$allowed_keys[] = 'meta_value';
$allowed_keys[] = 'meta_value_num';
}
$meta_query_clauses = $this->meta_query->get_clauses();
if ( $meta_query_clauses ) {
$allowed_keys = array_merge( $allowed_keys, array_keys( $meta_query_clauses ) );
}
$parsed = false;
if ( $this->query_vars['meta_key'] === $orderby || 'meta_value' === $orderby ) {
$parsed = "$wpdb->commentmeta.meta_value";
} elseif ( 'meta_value_num' === $orderby ) {
$parsed = "$wpdb->commentmeta.meta_value+0";
} elseif ( 'comment__in' === $orderby ) {
$comment__in = implode( ',', array_map( 'absint', $this->query_vars['comment__in'] ) );
$parsed = "FIELD( {$wpdb->comments}.comment_ID, $comment__in )";
} elseif ( in_array( $orderby, $allowed_keys, true ) ) {
if ( isset( $meta_query_clauses[ $orderby ] ) ) {
$meta_clause = $meta_query_clauses[ $orderby ];
$parsed = sprintf( 'CAST(%s.meta_value AS %s)', esc_sql( $meta_clause['alias'] ), esc_sql( $meta_clause['cast'] ) );
} else {
$parsed = "$wpdb->comments.$orderby";
}
}
return $parsed;
}
/**
* Parse an 'order' query variable and cast it to ASC or DESC as necessary.
*
* @since 4.2.0
*
* @param string $order The 'order' query variable.
* @return string The sanitized 'order' query variable.
*/
protected function parse_order( $order ) {
if ( ! is_string( $order ) || empty( $order ) ) {
return 'DESC';
}
if ( 'ASC' === strtoupper( $order ) ) {
return 'ASC';
} else {
return 'DESC';
}
}
}
/**
* REST API: WP_REST_Post_Types_Controller class
*
* @package WordPress
* @subpackage REST_API
* @since 4.7.0
*/
/**
* Core class to access post types via the REST API.
*
* @since 4.7.0
*
* @see WP_REST_Controller
*/
class WP_REST_Post_Types_Controller extends WP_REST_Controller {
/**
* Constructor.
*
* @since 4.7.0
*/
public function __construct() {
$this->namespace = 'wp/v2';
$this->rest_base = 'types';
}
/**
* Registers the routes for post types.
*
* @since 4.7.0
*
* @see register_rest_route()
*/
public function register_routes() {
register_rest_route(
$this->namespace,
'/' . $this->rest_base,
array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/(?P[\w-]+)',
array(
'args' => array(
'type' => array(
'description' => __( 'An alphanumeric identifier for the post type.' ),
'type' => 'string',
),
),
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => '__return_true',
'args' => array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
),
),
'schema' => array( $this, 'get_public_item_schema' ),
)
);
}
/**
* Checks whether a given request has permission to read types.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return true|WP_Error True if the request has read access, WP_Error object otherwise.
*/
public function get_items_permissions_check( $request ) {
if ( 'edit' === $request['context'] ) {
$types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
foreach ( $types as $type ) {
if ( current_user_can( $type->cap->edit_posts ) ) {
return true;
}
}
return new WP_Error(
'rest_cannot_view',
__( 'Sorry, you are not allowed to edit posts in this post type.' ),
array( 'status' => rest_authorization_required_code() )
);
}
return true;
}
/**
* Retrieves all public post types.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_items( $request ) {
$data = array();
$types = get_post_types( array( 'show_in_rest' => true ), 'objects' );
foreach ( $types as $type ) {
if ( 'edit' === $request['context'] && ! current_user_can( $type->cap->edit_posts ) ) {
continue;
}
$post_type = $this->prepare_item_for_response( $type, $request );
$data[ $type->name ] = $this->prepare_response_for_collection( $post_type );
}
return rest_ensure_response( $data );
}
/**
* Retrieves a specific post type.
*
* @since 4.7.0
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
*/
public function get_item( $request ) {
$obj = get_post_type_object( $request['type'] );
if ( empty( $obj ) ) {
return new WP_Error(
'rest_type_invalid',
__( 'Invalid post type.' ),
array( 'status' => 404 )
);
}
if ( empty( $obj->show_in_rest ) ) {
return new WP_Error(
'rest_cannot_read_type',
__( 'Cannot view post type.' ),
array( 'status' => rest_authorization_required_code() )
);
}
if ( 'edit' === $request['context'] && ! current_user_can( $obj->cap->edit_posts ) ) {
return new WP_Error(
'rest_forbidden_context',
__( 'Sorry, you are not allowed to edit posts in this post type.' ),
array( 'status' => rest_authorization_required_code() )
);
}
$data = $this->prepare_item_for_response( $obj, $request );
return rest_ensure_response( $data );
}
/**
* Prepares a post type object for serialization.
*
* @since 4.7.0
* @since 5.9.0 Renamed `$post_type` to `$item` to match parent class for PHP 8 named parameter support.
*
* @param WP_Post_Type $item Post type object.
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response Response object.
*/
public function prepare_item_for_response( $item, $request ) {
// Restores the more descriptive, specific name for use within this method.
$post_type = $item;
$taxonomies = wp_list_filter( get_object_taxonomies( $post_type->name, 'objects' ), array( 'show_in_rest' => true ) );
$taxonomies = wp_list_pluck( $taxonomies, 'name' );
$base = ! empty( $post_type->rest_base ) ? $post_type->rest_base : $post_type->name;
$namespace = ! empty( $post_type->rest_namespace ) ? $post_type->rest_namespace : 'wp/v2';
$supports = get_all_post_type_supports( $post_type->name );
$fields = $this->get_fields_for_response( $request );
$data = array();
if ( rest_is_field_included( 'capabilities', $fields ) ) {
$data['capabilities'] = $post_type->cap;
}
if ( rest_is_field_included( 'description', $fields ) ) {
$data['description'] = $post_type->description;
}
if ( rest_is_field_included( 'hierarchical', $fields ) ) {
$data['hierarchical'] = $post_type->hierarchical;
}
if ( rest_is_field_included( 'has_archive', $fields ) ) {
$data['has_archive'] = $post_type->has_archive;
}
if ( rest_is_field_included( 'visibility', $fields ) ) {
$data['visibility'] = array(
'show_in_nav_menus' => (bool) $post_type->show_in_nav_menus,
'show_ui' => (bool) $post_type->show_ui,
);
}
if ( rest_is_field_included( 'viewable', $fields ) ) {
$data['viewable'] = is_post_type_viewable( $post_type );
}
if ( rest_is_field_included( 'labels', $fields ) ) {
$data['labels'] = $post_type->labels;
}
if ( rest_is_field_included( 'name', $fields ) ) {
$data['name'] = $post_type->label;
}
if ( rest_is_field_included( 'slug', $fields ) ) {
$data['slug'] = $post_type->name;
}
if ( rest_is_field_included( 'icon', $fields ) ) {
$data['icon'] = $post_type->menu_icon;
}
if ( rest_is_field_included( 'supports', $fields ) ) {
$data['supports'] = $supports;
}
if ( rest_is_field_included( 'taxonomies', $fields ) ) {
$data['taxonomies'] = array_values( $taxonomies );
}
if ( rest_is_field_included( 'rest_base', $fields ) ) {
$data['rest_base'] = $base;
}
if ( rest_is_field_included( 'rest_namespace', $fields ) ) {
$data['rest_namespace'] = $namespace;
}
if ( rest_is_field_included( 'template', $fields ) ) {
$data['template'] = $post_type->template ?? array();
}
if ( rest_is_field_included( 'template_lock', $fields ) ) {
$data['template_lock'] = ! empty( $post_type->template_lock ) ? $post_type->template_lock : false;
}
$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
$data = $this->add_additional_fields_to_object( $data, $request );
$data = $this->filter_response_by_context( $data, $context );
// Wrap the data in a response object.
$response = rest_ensure_response( $data );
if ( rest_is_field_included( '_links', $fields ) || rest_is_field_included( '_embedded', $fields ) ) {
$response->add_links( $this->prepare_links( $post_type ) );
}
/**
* Filters a post type returned from the REST API.
*
* Allows modification of the post type data right before it is returned.
*
* @since 4.7.0
*
* @param WP_REST_Response $response The response object.
* @param WP_Post_Type $post_type The original post type object.
* @param WP_REST_Request $request Request used to generate the response.
*/
return apply_filters( 'rest_prepare_post_type', $response, $post_type, $request );
}
/**
* Prepares links for the request.
*
* @since 6.1.0
*
* @param WP_Post_Type $post_type The post type.
* @return array Links for the given post type.
*/
protected function prepare_links( $post_type ) {
return array(
'collection' => array(
'href' => rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ),
),
'https://api.w.org/items' => array(
'href' => rest_url( rest_get_route_for_post_type_items( $post_type->name ) ),
),
);
}
/**
* Retrieves the post type's schema, conforming to JSON Schema.
*
* @since 4.7.0
* @since 4.8.0 The `supports` property was added.
* @since 5.9.0 The `visibility` and `rest_namespace` properties were added.
* @since 6.1.0 The `icon` property was added.
*
* @return array Item schema data.
*/
public function get_item_schema() {
if ( $this->schema ) {
return $this->add_additional_fields_schema( $this->schema );
}
$schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'type',
'type' => 'object',
'properties' => array(
'capabilities' => array(
'description' => __( 'All capabilities used by the post type.' ),
'type' => 'object',
'context' => array( 'edit' ),
'readonly' => true,
),
'description' => array(
'description' => __( 'A human-readable description of the post type.' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
'hierarchical' => array(
'description' => __( 'Whether or not the post type should have children.' ),
'type' => 'boolean',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
'viewable' => array(
'description' => __( 'Whether or not the post type can be viewed.' ),
'type' => 'boolean',
'context' => array( 'edit' ),
'readonly' => true,
),
'labels' => array(
'description' => __( 'Human-readable labels for the post type for various contexts.' ),
'type' => 'object',
'context' => array( 'edit' ),
'readonly' => true,
),
'name' => array(
'description' => __( 'The title for the post type.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'slug' => array(
'description' => __( 'An alphanumeric identifier for the post type.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'supports' => array(
'description' => __( 'All features, supported by the post type.' ),
'type' => 'object',
'context' => array( 'edit' ),
'readonly' => true,
),
'has_archive' => array(
'description' => __( 'If the value is a string, the value will be used as the archive slug. If the value is false the post type has no archive.' ),
'type' => array( 'string', 'boolean' ),
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
'taxonomies' => array(
'description' => __( 'Taxonomies associated with post type.' ),
'type' => 'array',
'items' => array(
'type' => 'string',
),
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
'rest_base' => array(
'description' => __( 'REST base route for the post type.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'rest_namespace' => array(
'description' => __( 'REST route\'s namespace for the post type.' ),
'type' => 'string',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'visibility' => array(
'description' => __( 'The visibility settings for the post type.' ),
'type' => 'object',
'context' => array( 'edit' ),
'readonly' => true,
'properties' => array(
'show_ui' => array(
'description' => __( 'Whether to generate a default UI for managing this post type.' ),
'type' => 'boolean',
),
'show_in_nav_menus' => array(
'description' => __( 'Whether to make the post type available for selection in navigation menus.' ),
'type' => 'boolean',
),
),
),
'icon' => array(
'description' => __( 'The icon for the post type.' ),
'type' => array( 'string', 'null' ),
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'template' => array(
'type' => array( 'array' ),
'description' => __( 'The block template associated with the post type.' ),
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
'template_lock' => array(
'type' => array( 'string', 'boolean' ),
'enum' => array( 'all', 'insert', 'contentOnly', false ),
'description' => __( 'The template_lock associated with the post type, or false if none.' ),
'readonly' => true,
'context' => array( 'view', 'edit', 'embed' ),
),
),
);
$this->schema = $schema;
return $this->add_additional_fields_schema( $this->schema );
}
/**
* Retrieves the query params for collections.
*
* @since 4.7.0
*
* @return array Collection parameters.
*/
public function get_collection_params() {
return array(
'context' => $this->get_context_param( array( 'default' => 'view' ) ),
);
}
}