* Taxonomy API: WP_Term_Query class.
* Class used for querying terms.
* @see WP_Term_Query::__construct() for accepted arguments.
#[AllowDynamicProperties]
* SQL string used to perform database query.
* Metadata query container.
* @var WP_Meta_Query A meta query instance.
public $meta_query = false;
* Metadata query clauses.
protected $meta_query_clauses;
protected $sql_clauses = array(
* Query vars set by the user.
* Default values for query vars.
public $query_var_defaults;
* List of terms located by the query.
* Sets up the term query, based on the query vars passed.
* @since 4.6.0 Introduced 'term_taxonomy_id' parameter.
* @since 4.7.0 Introduced 'object_ids' parameter.
* @since 4.9.0 Added 'slug__in' support for 'orderby'.
* @since 5.1.0 Introduced the 'meta_compare_key' parameter.
* @since 5.3.0 Introduced the 'meta_type_key' parameter.
* @since 6.4.0 Introduced the 'cache_results' parameter.
* @param string|array $query {
* Optional. Array or query string of term query parameters. Default empty.
* @type string|string[] $taxonomy Taxonomy name, or array of taxonomy names, to which results
* @type int|int[] $object_ids Object ID, or array of object IDs. Results will be
* limited to terms associated with these objects.
* @type string $orderby Field(s) to order terms by. Accepts:
* - Term fields ('name', 'slug', 'term_group', 'term_id', 'id',
* 'description', 'parent', 'term_order'). Unless `$object_ids`
* is not empty, 'term_order' is treated the same as 'term_id'.
* - 'count' to use the number of objects associated with the term.
* - 'include' to match the 'order' of the `$include` param.
* - 'slug__in' to match the 'order' of the `$slug` param.
* - The value of `$meta_key`.
* - The array keys of `$meta_query`.
* - 'none' to omit the ORDER BY clause.
* @type string $order Whether to order terms in ascending or descending order.
* Accepts 'ASC' (ascending) or 'DESC' (descending).
* @type bool|int $hide_empty Whether to hide terms not assigned to any posts. Accepts
* 1|true or 0|false. Default 1|true.
* @type int[]|string $include Array or comma/space-separated string of term IDs to include.
* @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude.
* If `$include` is non-empty, `$exclude` is ignored.
* @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude
* along with all of their descendant terms. If `$include` is
* non-empty, `$exclude_tree` is ignored. Default empty array.
* @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any
* positive number. Default ''|0 (all). Note that `$number` may
* not return accurate results when coupled with `$object_ids`.
* See #41796 for details.
* @type int $offset The number by which to offset the terms query. Default empty.
* @type string $fields Term fields to query for. Accepts:
* - 'all' Returns an array of complete term objects (`WP_Term[]`).
* - 'all_with_object_id' Returns an array of term objects
* with the 'object_id' param (`WP_Term[]`). Works only
* when the `$object_ids` parameter is populated.
* - 'ids' Returns an array of term IDs (`int[]`).
* - 'tt_ids' Returns an array of term taxonomy IDs (`int[]`).
* - 'names' Returns an array of term names (`string[]`).
* - 'slugs' Returns an array of term slugs (`string[]`).
* - 'count' Returns the number of matching terms (`int`).
* - 'id=>parent' Returns an associative array of parent term IDs,
* keyed by term ID (`int[]`).
* - 'id=>name' Returns an associative array of term names,
* keyed by term ID (`string[]`).
* - 'id=>slug' Returns an associative array of term slugs,
* keyed by term ID (`string[]`).
* @type string|string[] $name Name or array of names to return term(s) for.
* @type string|string[] $slug Slug or array of slugs to return term(s) for.
* @type int|int[] $term_taxonomy_id Term taxonomy ID, or array of term taxonomy IDs,
* to match when querying terms.
* @type bool $hierarchical Whether to include terms that have non-empty descendants
* (even if `$hide_empty` is set to true). Default true.
* @type string $search Search criteria to match terms. Will be SQL-formatted with
* wildcards before and after. Default empty.
* @type string $name__like Retrieve terms with criteria by which a term is LIKE
* `$name__like`. Default empty.
* @type string $description__like Retrieve terms where the description is LIKE
* `$description__like`. Default empty.
* @type bool $pad_counts Whether to pad the quantity of a term's children in the
* quantity of each term's "count" object variable.
* @type string $get Whether to return terms regardless of ancestry or whether the
* terms are empty. Accepts 'all' or '' (disabled).
* @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies
* are passed, `$child_of` is ignored. Default 0.
* @type int $parent Parent term ID to retrieve direct-child terms of.
* @type bool $childless True to limit results to terms that have no children.
* This parameter has no effect on non-hierarchical taxonomies.
* @type string $cache_domain Unique cache key to be produced when this query is stored in
* an object cache. Default 'core'.
* @type bool $cache_results Whether to cache term information. Default true.
* @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true.
* @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.
public function __construct( $query = '' ) {
$this->query_var_defaults = array(
'exclude_tree' => array(),
'term_taxonomy_id' => '',
'description__like' => '',
'cache_domain' => 'core',
'update_term_meta_cache' => true,
if ( ! empty( $query ) ) {
* Parse arguments passed to the term query with default query parameters.
* @param string|array $query WP_Term_Query arguments. See WP_Term_Query::__construct() for accepted arguments.
public function parse_query( $query = '' ) {
$query = $this->query_vars;
$taxonomies = isset( $query['taxonomy'] ) ? (array) $query['taxonomy'] : null;
* Filters the terms query default arguments.
* Use {@see 'get_terms_args'} to filter the passed arguments.
* @param array $defaults An array of default get_terms() arguments.
* @param string[] $taxonomies An array of taxonomy names.
$this->query_var_defaults = apply_filters( 'get_terms_defaults', $this->query_var_defaults, $taxonomies );
$query = wp_parse_args( $query, $this->query_var_defaults );
$query['number'] = absint( $query['number'] );
$query['offset'] = absint( $query['offset'] );
// 'parent' overrides 'child_of'.
if ( 0 < (int) $query['parent'] ) {
$query['child_of'] = false;
if ( 'all' === $query['get'] ) {
$query['childless'] = false;
$query['hide_empty'] = 0;
$query['hierarchical'] = false;
$query['pad_counts'] = false;
$query['taxonomy'] = $taxonomies;
$this->query_vars = $query;
* Fires after term query vars have been parsed.
* @param WP_Term_Query $query Current instance of WP_Term_Query.
do_action( 'parse_term_query', $this );
* Sets up the query and retrieves the results.
* The return type varies depending on the value passed to `$args['fields']`. See
* WP_Term_Query::get_terms() for details.
* @param string|array $query Array or URL query string of parameters.
* @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
* when 'count' is passed to `$args['fields']`.
public function query( $query ) {
$this->query_vars = wp_parse_args( $query );
return $this->get_terms();
* Retrieves the query results.
* The return type varies depending on the value passed to `$args['fields']`.
* The following will result in an array of `WP_Term` objects being returned:
* The following will result in a numeric string being returned:
* The following will result in an array of text strings being returned:
* The following will result in an array of numeric strings being returned:
* The following will result in an array of integers being returned:
* @global wpdb $wpdb WordPress database abstraction object.
* @return WP_Term[]|int[]|string[]|string Array of terms, or number of terms as numeric string
* when 'count' is passed to `$args['fields']`.
public function get_terms() {
$this->parse_query( $this->query_vars );
$args = &$this->query_vars;
// Set up meta_query so it's available to 'pre_get_terms'.
$this->meta_query = new WP_Meta_Query();
$this->meta_query->parse_query_vars( $args );
* Fires before terms are retrieved.
* @param WP_Term_Query $query Current instance of WP_Term_Query (passed by reference).
do_action_ref_array( 'pre_get_terms', array( &$this ) );
$taxonomies = (array) $args['taxonomy'];
// Save queries by not crawling the tree in the case of multiple taxes or a flat tax.
$has_hierarchical_tax = false;
foreach ( $taxonomies as $_tax ) {
if ( is_taxonomy_hierarchical( $_tax ) ) {
$has_hierarchical_tax = true;
// When no taxonomies are provided, assume we have to descend the tree.
$has_hierarchical_tax = true;
if ( ! $has_hierarchical_tax ) {
$args['hierarchical'] = false;
$args['pad_counts'] = false;
// 'parent' overrides 'child_of'.
if ( 0 < (int) $args['parent'] ) {
$args['child_of'] = false;
if ( 'all' === $args['get'] ) {
$args['childless'] = false;
$args['hierarchical'] = false;
$args['pad_counts'] = false;
* Filters the terms query arguments.
* @param array $args An array of get_terms() arguments.
* @param string[] $taxonomies An array of taxonomy names.
$args = apply_filters( 'get_terms_args', $args, $taxonomies );
// Avoid the query if the queried parent/child_of term has no descendants.
$child_of = $args['child_of'];
$parent = $args['parent'];
foreach ( $taxonomies as $_tax ) {
$hierarchy = _get_term_hierarchy( $_tax );
if ( isset( $hierarchy[ $_parent ] ) ) {
if ( 'count' === $args['fields'] ) {
// 'term_order' is a legal sort order only when joining the relationship table.
$_orderby = $this->query_vars['orderby'];
if ( 'term_order' === $_orderby && empty( $this->query_vars['object_ids'] ) ) {
$orderby = $this->parse_orderby( $_orderby );
$orderby = "ORDER BY $orderby";
$order = $this->parse_order( $this->query_vars['order'] );
$this->sql_clauses['where']['taxonomy'] =
"tt.taxonomy IN ('" . implode( "', '", array_map( 'esc_sql', $taxonomies ) ) . "')";
if ( empty( $args['exclude'] ) ) {
$args['exclude'] = array();
if ( empty( $args['include'] ) ) {
$args['include'] = array();
$exclude = $args['exclude'];
$exclude_tree = $args['exclude_tree'];
$include = $args['include'];
if ( ! empty( $include ) ) {
$inclusions = implode( ',', wp_parse_id_list( $include ) );
if ( ! empty( $inclusions ) ) {
$this->sql_clauses['where']['inclusions'] = 't.term_id IN ( ' . $inclusions . ' )';
if ( ! empty( $exclude_tree ) ) {
$exclude_tree = wp_parse_id_list( $exclude_tree );
$excluded_children = $exclude_tree;
foreach ( $exclude_tree as $extrunk ) {
$excluded_children = array_merge(
'taxonomy' => reset( $taxonomies ),
'child_of' => (int) $extrunk,
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
