Class: WP_Term_Query

Class used for querying terms.


Properties

Name Type(s) Default Value Summary
request string SQL string used to perform database query.
meta_query object Metadata query container.
meta_query_clauses array Metadata query clauses.
sql_clauses array SQL query clauses.
query_vars array Query vars set by the user.
query_var_defaults array Default values for query vars.
terms array List of terms located by the query.

Methods

WP_Term_Query:: __construct( string | array $query = '' )

Constructor. Since 4.6.0. Since 4.6.0. Since 4.7.0. Since 4.9.0.

Sets up the term query, based on the query vars passed.

Arguments

Name Type(s) Default Value Description
$query string | array

{ Optional. Array or query string of term query parameters. Default empty.

@type string|array $taxonomy               Taxonomy name, or array of taxonomies, to which results should
                                           be limited.
@type int|array    $object_ids             Optional. 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'),
                                           'count' for term taxonomy count, 'include' to match the
                                           'order' of the $include param, 'slug__in' to match the
                                           'order' of the $slug param, 'meta_value', 'meta_value_num',
                                           the value of `$meta_key`, the array keys of `$meta_query`, or
                                           'none' to omit the ORDER BY clause. Defaults to 'name'.
@type string       $order                  Whether to order terms in ascending or descending order.
                                           Accepts 'ASC' (ascending) or 'DESC' (descending).
                                           Default 'ASC'.
@type bool|int     $hide_empty             Whether to hide terms not assigned to any posts. Accepts
                                           1|true or 0|false. Default 1|true.
@type array|string $include                Array or comma/space-separated string of term ids to include.
                                           Default empty array.
@type array|string $exclude                Array or comma/space-separated string of term ids to exclude.
                                           If $include is non-empty, $exclude is ignored.
                                           Default empty array.
@type array|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), 'all_with_object_id' (returns an
                                           array of term objects with the 'object_id' param; only works
                                           when the `$fields` parameter is 'object_ids' ), 'ids'
                                           (returns an array of ids), 'tt_ids' (returns an array of
                                           term taxonomy ids), 'id=>parent' (returns an associative
                                           array with ids as keys, parent term IDs as values), 'names'
                                           (returns an array of term names), 'count' (returns the number
                                           of matching terms), 'id=>name' (returns an associative array
                                           with ids as keys, term names as values), or 'id=>slug'
                                           (returns an associative array with ids as keys, term slugs
                                           as values). Default 'all'.
@type bool         $count                  Whether to return a term count (true) or array of term objects
                                           (false). Will take precedence over `$fields` if true.
                                           Default false.
@type string|array $name                   Optional. Name or array of names to return term(s) for.
                                           Default empty.
@type string|array $slug                   Optional. Slug or array of slugs to return term(s) for.
                                           Default empty.
@type int|array    $term_taxonomy_id       Optional. 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.
                                           Default false.
@type string       $get                    Whether to return terms regardless of ancestry or whether the
                                           terms are empty. Accepts 'all' or empty (disabled).
                                           Default empty.
@type int          $child_of               Term ID to retrieve child terms of. If multiple taxonomies
                                           are passed, $child_of is ignored. Default 0.
@type int|string   $parent                 Parent term ID to retrieve direct-child terms of.
                                           Default empty.
@type bool         $childless              True to limit results to terms that have no children.
                                           This parameter has no effect on non-hierarchical taxonomies.
                                           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_term_meta_cache Whether to prime meta caches for matched terms. Default true.
@type array        $meta_query             Optional. Meta query clauses to limit retrieved terms by.
                                           See `WP_Meta_Query`. Default empty.
@type string       $meta_key               Limit terms to those matching a specific metadata key.
                                           Can be used in conjunction with `$meta_value`. Default empty.
@type string       $meta_value             Limit terms to those matching a specific metadata value.
                                           Usually used in conjunction with `$meta_key`. Default empty.
@type string       $meta_type              MySQL data type that the `$meta_value` will be CAST to for
                                           comparisons. Default empty.
@type string       $meta_compare           Comparison operator to test the 'meta_value'. Default empty.

}


WP_Term_Query:: get_search_sql( string $string )

Used internally to generate a SQL string related to the 'search' parameter. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$string string

Returns

string


WP_Term_Query:: get_terms( )

Get terms, based on query_vars. Since 4.6.0.

Returns

array

List of terms.


WP_Term_Query:: parse_order( string $order )

Parse an 'order' query variable and cast it to ASC or DESC as necessary. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$order string

The 'order' query variable.

Returns

string

The sanitized 'order' query variable.


WP_Term_Query:: parse_orderby( string $orderby_raw )

Parse and sanitize 'orderby' keys passed to the term query. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$orderby_raw string

Alias for the field to order by.

Returns

string | false

Value to used in the ORDER clause. False otherwise.


WP_Term_Query:: parse_orderby_meta( string $orderby_raw )

Generate the ORDER BY clause for an 'orderby' param that is potentially related to a meta query. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$orderby_raw string

Raw 'orderby' value passed to WP_Term_Query.

Returns

string

ORDER BY clause.


WP_Term_Query:: parse_query( string | array $query = '' )

Parse arguments passed to the term query with default query parameters. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$query string | array

WP_Term_Query arguments. See WP_Term_Query::__construct()


WP_Term_Query:: populate_terms( array $term_ids )

Creates an array of term objects from an array of term IDs. Since 4.9.8.

Also discards invalid term objects.

Arguments

Name Type(s) Default Value Description
$term_ids array

Term IDs.

Returns

array


WP_Term_Query:: query( string | array $query )

Sets up the query for retrieving terms. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$query string | array

Array or URL query string of parameters.

Returns

array | integer

List of terms, or number of terms when 'count' is passed as a query var.


WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.