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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$querystring|arrayoptional

Array or query string of term query parameters. Default empty.Default: ''

• $taxonomystring|string[]

  Taxonomy name, or array of taxonomy names, to which results should be limited.

• $object_idsint|int[]

  Object ID, or array of object IDs. Results will be limited to terms associated with these objects.

• $orderbystringdefault: 'name'

  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. - 'meta_value' - 'meta_value_num'. - The value of $meta_key. - The array keys of $meta_query. - 'none' to omit the ORDER BY clause.

• $orderstringdefault: 'ASC'

  Whether to order terms in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending).

• $hide_emptybool|intdefault: 1|true

  Whether to hide terms not assigned to any posts. Accepts 1|true or 0|false.

• $includeint[]|stringdefault: empty array

  Array or comma/space-separated string of term IDs to include.

• $excludeint[]|stringdefault: empty array

  Array or comma/space-separated string of term IDs to exclude. If $include is non-empty, $exclude is ignored.

• $exclude_treeint[]|stringdefault: empty array

  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.

• $numberint|string

  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.

• $offsetintdefault: empty

  The number by which to offset the terms query.

• $fieldsstringdefault: 'all'

  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[]).

• $namestring|string[]default: empty

  Name or array of names to return term(s) for.

• $slugstring|string[]default: empty

  Slug or array of slugs to return term(s) for.

• $term_taxonomy_idint|int[]

  Term taxonomy ID, or array of term taxonomy IDs, to match when querying terms.

• $hierarchicalbooldefault: true

  Whether to include terms that have non-empty descendants (even if $hide_empty is set to true).

• $searchstringdefault: empty

  Search criteria to match terms. Will be SQL-formatted with wildcards before and after.

• $name__likestringdefault: empty

  Retrieve terms with criteria by which a term is LIKE $name__like.

• $description__likestringdefault: 0

  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 '' (disabled). Default ''. @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies are passed,$child_of` is ignored.

• $parentintdefault: empty

  Parent term ID to retrieve direct-child terms of.

• $childlessbooldefault: false

  True to limit results to terms that have no children. This parameter has no effect on non-hierarchical taxonomies.

• $cache_domainstringdefault: 'core'

  Unique cache key to be produced when this query is stored in an object cache.

• $cache_resultsbooldefault: true

  Whether to cache term information.

• $update_term_meta_cachebooldefault: true

  Whether to prime meta caches for matched terms.

• $meta_keystring|string[]

  Meta key or keys to filter by.

• $meta_valuestring|string[]

  Meta value or values to filter by.

• $meta_comparestring

  MySQL operator used for comparing the meta value. See WP_Meta_Query::construct() for accepted values and default value.

• $meta_compare_keystring

  MySQL operator used for comparing the meta key. See WP_Meta_Query::</strong>construct() for accepted values and default value.

• $meta_typestring

  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.

• $meta_type_keystring

  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.

• $meta_queryarray

  An associative array of WP_Meta_Query arguments. See WP_Meta_Query::</strong>construct() for accepted values.

Performance profile

How much work a call to WP_Term_Query::__construct() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Trivial

Reaches the database via ->query().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

6–9

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 9.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

6

6 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• sqldatabase query->query()called directly

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Term_Query::__construct() can have, taken from its control-flow graph on PHP 8.5.

Uses · 1

• WP_Term_Query::query()Sets up the query and retrieves the results.

Used by · 6

• WP_REST_Term_Search_Handler::search_items()Searches terms for a given search request.
• WP_Sitemaps_Taxonomies::get_url_list()Gets a URL list for a taxonomy sitemap.
• WP_Tax_Query::transform_query()Transforms a single query, from one field to another.
• _wp_build_title_and_description_for_taxonomy_block_template()Builds the title and description of a taxonomy-specific template based on the underlying entity referenced.
• get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
• render_block_core_term_template()Renders the `core/term-template` block on the server.

Source code

View on Trac ↗View on GitHub ↗

196	public function __construct( $query = '' ) {197		$this->query_var_defaults = array(198			'taxonomy'               => null,199			'object_ids'             => null,200			'orderby'                => 'name',201			'order'                  => 'ASC',202			'hide_empty'             => true,203			'include'                => array(),204			'exclude'                => array(),205			'exclude_tree'           => array(),206			'number'                 => '',207			'offset'                 => '',208			'fields'                 => 'all',209			'name'                   => '',210			'slug'                   => '',211			'term_taxonomy_id'       => '',212			'hierarchical'           => true,213			'search'                 => '',214			'name__like'             => '',215			'description__like'      => '',216			'pad_counts'             => false,217			'get'                    => '',218			'child_of'               => 0,219			'parent'                 => '',220			'childless'              => false,221			'cache_domain'           => 'core',222			'cache_results'          => true,223			'update_term_meta_cache' => true,224			'meta_query'             => '',225			'meta_key'               => '',226			'meta_value'             => '',227			'meta_type'              => '',228			'meta_compare'           => '',229		);230 231		if ( ! empty( $query ) ) {232			$this->query( $query );233		}234	}

Changelog

Introduced in 6.4.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/class-wp-term-query.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.