wp_get_object_terms( int|int[] $object_ids, string|string[] $taxonomies, array|string $args = array() ): WP_Term[]|int[]|string[]|string|WP_Error

Compatibility

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

Parameters

$object_idsint|int[]

The ID(s) of the object(s) to retrieve.

$taxonomiesstring|string[]

The taxonomy names to retrieve terms from.

$argsarray|stringoptional

See WP_Term_Query::__construct() for supported arguments.Default: array()

Return value

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

Array of terms, a count thereof as a numeric string, or WP_Error if any of the taxonomies do not exist.
See WP_Term_Query::get_terms() for more information.

Performance profile

How much work a call to wp_get_object_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 wp_get_object_terms().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

6–103

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

Plugin surface

3 hooks

Third-party callbacks on 'wp_get_object_terms_args', 'get_object_terms', 'wp_get_object_terms' run inside this call, and their cost is not bounded by anything here.

Called by

27

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

What it touches

• querycontent querywp_get_object_terms()this function does it
• hookthird-party callbacksapply_filters()called directly

Further down the call graph this can also reach option, cache, 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 · 11 distinct outcomes

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

Hooks and filters fired · 3

3 hooks fire while wp_get_object_terms() runs, in this order:

1. 1
   apply_filters( wp_get_object_terms_args )filterline 2290 (+36 into the body)

   Filters arguments for retrieving object terms.

2. 2
   apply_filters( get_object_terms )filterline 2338 (+84 into the body)

   Filters the terms for a given object or objects.

3. 3
   apply_filters( wp_get_object_terms )filterline 2357 (+103 into the body)

   Filters the terms for a given object or objects.

Uses · 9

• taxonomy_exists()Determines whether the taxonomy name exists.
• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_taxonomy()Retrieves the taxonomy object of $taxonomy.
• wp_get_object_terms()Retrieves the terms associated with the given object(s), in the supplied taxonomies.
• get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• WP_Error::__construct()Initializes the error.

Used by · 27

• WP_REST_Terms_Controller::get_items()Retrieves terms associated with a taxonomy.
• _update_term_count_on_transition_post_status()Updates the custom taxonomies' term counts when a post's status is changed.
• _wp_menu_item_classes_by_context()Adds the class property classes for the current context, if applicable.
• bulk_edit_posts()Processes the post data for the bulk editing of posts.
• get_adjacent_post()Retrieves the adjacent post.
• get_attachment_fields_to_edit()Retrieves the attachment fields to edit form fields.
• get_bookmark()Retrieves bookmark data.
• get_boundary_post()Retrieves the boundary post.
• get_compat_media_markup()
• get_inline_data()Adds hidden fields with the data for use in the inline editor for posts and pages.
• get_terms_to_edit()Gets comma-separated list of terms available to edit for the given post ID.
• get_the_taxonomies()Retrieves all taxonomies associated with a post.

Source code

View on Trac ↗View on GitHub ↗

2254function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {2255	if ( empty( $object_ids ) || empty( $taxonomies ) ) {2256		return array();2257	}2258 2259	if ( ! is_array( $taxonomies ) ) {2260		$taxonomies = array( $taxonomies );2261	}2262 2263	foreach ( $taxonomies as $taxonomy ) {2264		if ( ! taxonomy_exists( $taxonomy ) ) {2265			return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );2266		}2267	}2268 2269	if ( ! is_array( $object_ids ) ) {2270		$object_ids = array( $object_ids );2271	}2272	$object_ids = array_map( 'intval', $object_ids );2273 2274	$defaults = array(2275		'update_term_meta_cache' => false,2276	);2277 2278	$args = wp_parse_args( $args, $defaults );2279 2280	/**2281	 * Filters arguments for retrieving object terms.2282	 *2283	 * @since 4.9.02284	 *2285	 * @param array    $args       An array of arguments for retrieving terms for the given object(s).2286	 *                             See {@see wp_get_object_terms()} for details.2287	 * @param int[]    $object_ids Array of object IDs.2288	 * @param string[] $taxonomies Array of taxonomy names to retrieve terms from.2289	 */2290	$args = apply_filters( 'wp_get_object_terms_args', $args, $object_ids, $taxonomies );2291 2292	/*2293	 * When one or more queried taxonomies is registered with an 'args' array,2294	 * those params override the `$args` passed to this function.2295	 */2296	$terms = array();2297	if ( count( $taxonomies ) > 1 ) {2298		foreach ( $taxonomies as $index => $taxonomy ) {2299			$t = get_taxonomy( $taxonomy );2300			if ( isset( $t->args ) && is_array( $t->args ) && array_merge( $args, $t->args ) != $args ) {2301				unset( $taxonomies[ $index ] );2302				$terms = array_merge( $terms, wp_get_object_terms( $object_ids, $taxonomy, array_merge( $args, $t->args ) ) );2303			}2304		}2305	} else {2306		$t = get_taxonomy( $taxonomies[0] );2307		if ( isset( $t->args ) && is_array( $t->args ) ) {2308			$args = array_merge( $args, $t->args );2309		}2310	}2311 2312	$args['taxonomy']   = $taxonomies;2313	$args['object_ids'] = $object_ids;2314 2315	// Taxonomies registered without an 'args' param are handled here.2316	if ( ! empty( $taxonomies ) ) {2317		$terms_from_remaining_taxonomies = get_terms( $args );2318 2319		// Array keys should be preserved for values of $fields that use term_id for keys.2320		if ( ! empty( $args['fields'] ) && str_starts_with( $args['fields'], 'id=>' ) ) {2321			$terms = $terms + $terms_from_remaining_taxonomies;2322		} else {2323			$terms = array_merge( $terms, $terms_from_remaining_taxonomies );2324		}2325	}2326 2327	/**2328	 * Filters the terms for a given object or objects.2329	 *2330	 * @since 4.2.02331	 *2332	 * @param WP_Term[]|int[]|string[]|string $terms      Array of terms or a count thereof as a numeric string.2333	 * @param int[]                           $object_ids Array of object IDs for which terms were retrieved.

Changelog

Introduced in 4.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 6.7.7 tag, from src/wp-includes/taxonomy.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.