wp_get_object_terms()
Gets the terms (taxonomy elements) related to the given object(s) (posts) in the specified taxonomy.
This function is the core of the function get_the_terms(). In most cases, it is better to use get_the_terms() instead of this function, because the result is cached there and can potentially save many additional queries.
This is especially useful if you are iterating over post results in a loop, because WP_Query{} by default loads all terms for the queried posts.
Note: this function can accept multiple posts and multiple taxonomy names to get all data at once, while get_the_terms() works with a single post and a single taxonomy.
Hooks from the function
Returns
WP_Term[]|Int[]|String[]|String|WP_Error.
Array of objectscontaining information about the terms. On error, it will return a WP_Error object.array()- if no elements are found.WP_Error- if the specified taxonomy does not exist.
Usage
wp_get_object_terms( $object_ids, $taxonomies, $args );
- $object_ids(string/array) (required)
- ID of the objects whose terms need to be retrieved. More than one ID should be specified in an array: array(23, 56, 89).
- $taxonomies(string/array) (required)
- The name of the taxonomy whose terms need to be retrieved. Multiple names can be specified. Multiple names should be passed in an array: array('category', 'name2').
- $args(string/array)
Arguments according to which the result will be obtained. Can be specified as a query string.
Starting from WP 4.7, all parameters of the function get_terms() can be specified.
Default: presets
-
orderby(string)
By which criterion to sort the result. Can be:name- by name. Default.count- by the number of posts.slug- by slug.term_group-term_order-none- output without sorting.
Default: 'name'
-
order(string)
Sorting direction.ASC— in order,DESC— in reverse order.
Default: 'ASC' -
fields(string)
Which fields to include in the resulting array. Can be:all- the result will be an array of objects with all information about each term.ids- get only the term IDs.names- get only the term names.slugs- get only the term slugs.all_with_object_id- the same as all, plus the term IDs.tt_ids- will return the taxonomy term IDs (internal ID for table relations).
Combined options are also possible, for example:
id=>name- will return a pair ID => Name.id=>slug- will return a pair ID => Slug.
Default: 'all'
-
meta_query(array)
Meta query parameters. See WP_Meta_Query{}. Since version 4.4. - update_term_meta_cache(boolean)
Whether to update the metadata cache of the retrieved taxonomy elements. Since version 4.4.
Default: false (was true until WP 6.3)
-
Examples
#1 All elements of the 'product_categories' taxonomy post
Get the terms of the product_categories taxonomy of the current post ($post->ID):
$product_cats = wp_get_object_terms( $post->ID, 'product_categories' );
#2 Returns the list of elements of the "product" taxonomy that are set for the posts:
$product_terms = wp_get_object_terms( $post->ID, 'product' );
if( $product_terms && ! is_wp_error( $product_terms ) ){
$lis = [];
foreach( $product_terms as $term ){
$lis[] = '<li><a href="'. get_term_link( $term ) .'">'. esc_html( $term->name ) .'</a></li>';
}
echo '<ul>'. implode( "\n", $lis ) .'</ul>';
} #3 Gets the topmost taxonomy element for the specified or current post in the loop
See the example in the get_the_terms() description.
Changelog
| Since 2.3.0 | Introduced. |
| Since 4.2.0 | Added support for 'taxonomy', 'parent', and 'term_taxonomy_id' values of $orderby. Introduced $parent argument. |
| Since 4.4.0 | Introduced $meta_query and $update_term_meta_cache arguments. When $fields is 'all' or 'all_with_object_id', an array of WP_Term objects will be returned. |
| Since 4.7.0 | Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments. |
| Since 6.3.0 | Passing update_term_meta_cache argument value false by default resulting in get_terms() to not prime the term meta cache. |