WP_Term_Query::get_terms(): WP_Term[]|int[]|string[]|string

Description

Compatibility

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

Return value

WP_Term[]|int[]|string[]|string

Array of terms, or number of terms as numeric string when 'count' is passed to $args['fields'].

Performance profile

How much work a call to WP_Term_Query::get_terms() 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

Heavy

Reaches the database via ->get_results().

Scaling

Scales with input

The body loops, so the work grows with how much data it finds.

Instructions

374–410

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

Plugin surface

6 hooks

Third-party callbacks on 'pre_get_terms', 'get_terms_args', 'list_terms_exclusions' run inside this call, and their cost is not bounded by anything here.

Called by

1

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

What it touches

• hookthird-party callbacksdo_action_ref_array()called directly
• querycontent queryget_terms()called directly
• cacheobject cachewp_cache_get()called directly
• sqldatabase query->get_results()called directly
• optionoption read or writeget_option()one call below WP_Term_Query::get_terms()

Further down the call graph this can also reach serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 16 distinct outcomes

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

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 6

6 hooks fire while WP_Term_Query::get_terms() runs, in this order:

1. 1
   do_action( pre_get_terms )actionline 365 (+17 into the body)

   Fires before terms are retrieved.

2. 2
   apply_filters( get_terms_args )filterline 408 (+60 into the body)

   Filters the terms query arguments.

3. 3
   apply_filters( list_terms_exclusions )filterline 534 (+186 into the body)

   Filters the terms to exclude from the terms query.

4. 4
   apply_filters( get_terms_fields )filterline 699 (+351 into the body)

   Filters the fields to select in the terms query.

5. 5
   apply_filters( terms_clauses )filterline 731 (+383 into the body)

   Filters the terms query SQL clauses.

6. 6
   apply_filters( terms_pre_query )filterline 773 (+425 into the body)

   Filters the terms array before the query takes place.

Uses · 27

• do_action_ref_array()Calls the callback functions that have been added to an action hook, specifying arguments in an array.
• is_taxonomy_hierarchical()Determines whether the taxonomy object is hierarchical.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• _get_term_hierarchy()Retrieves children of taxonomy as term IDs.
• wp_parse_id_list()Cleans up an array, comma- or space-separated list of IDs.
• get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
• sanitize_term_field()Sanitizes the field value in the term based on the context.
• apply_filters_ref_array()Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
• wp_cache_get()Retrieves the cache contents from the cache by key and group.
• wp_list_pluck()Plucks a certain field out of each object or array in an array.
• _prime_term_caches()Adds any terms from the given IDs to the cache that do not already exist in cache.
• wp_cache_set()Saves the data to the cache.

Used by · 1

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

Source code

View on Trac ↗View on GitHub ↗

348	public function get_terms() {349		global $wpdb;350 351		$this->parse_query( $this->query_vars );352		$args = &$this->query_vars;353 354		// Set up meta_query so it's available to 'pre_get_terms'.355		$this->meta_query = new WP_Meta_Query();356		$this->meta_query->parse_query_vars( $args );357 358		/**359		 * Fires before terms are retrieved.360		 *361		 * @since 4.6.0362		 *363		 * @param WP_Term_Query $query Current instance of WP_Term_Query (passed by reference).364		 */365		do_action_ref_array( 'pre_get_terms', array( &$this ) );366 367		$taxonomies = (array) $args['taxonomy'];368 369		// Save queries by not crawling the tree in the case of multiple taxes or a flat tax.370		$has_hierarchical_tax = false;371		if ( $taxonomies ) {372			foreach ( $taxonomies as $_tax ) {373				if ( is_taxonomy_hierarchical( $_tax ) ) {374					$has_hierarchical_tax = true;375				}376			}377		} else {378			// When no taxonomies are provided, assume we have to descend the tree.379			$has_hierarchical_tax = true;380		}381 382		if ( ! $has_hierarchical_tax ) {383			$args['hierarchical'] = false;384			$args['pad_counts']   = false;385		}386 387		// 'parent' overrides 'child_of'.388		if ( 0 < (int) $args['parent'] ) {389			$args['child_of'] = false;390		}391 392		if ( 'all' === $args['get'] ) {393			$args['childless']    = false;394			$args['child_of']     = 0;395			$args['hide_empty']   = 0;396			$args['hierarchical'] = false;397			$args['pad_counts']   = false;398		}399 400		/**401		 * Filters the terms query arguments.402		 *403		 * @since 3.1.0404		 *405		 * @param array    $args       An array of get_terms() arguments.406		 * @param string[] $taxonomies An array of taxonomy names.407		 */408		$args = apply_filters( 'get_terms_args', $args, $taxonomies );409 410		// Avoid the query if the queried parent/child_of term has no descendants.411		$child_of = $args['child_of'];412		$parent   = $args['parent'];413 414		if ( $child_of ) {415			$_parent = $child_of;416		} elseif ( $parent ) {417			$_parent = $parent;418		} else {419			$_parent = false;420		}421 422		if ( $_parent ) {423			$in_hierarchy = false;424			foreach ( $taxonomies as $_tax ) {425				$hierarchy = _get_term_hierarchy( $_tax );426 427				if ( isset( $hierarchy[ $_parent ] ) ) {

Changelog

Introduced in 4.6.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 6.7.7 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.