wp_get_object_terms

Retrieves the terms associated with the given object(s), in the supplied taxonomies.

Description

(array|WP_Error) wp_get_object_terms( (int|array) $object_ids, (string|array) $taxonomies, (array) $args = array() ); 

Returns (array|WP_Error)

The requested term data or empty array if no terms found. WP_Error if any of the $taxonomies don't exist.

Parameters (3)

0. $object_ids (int|array)
The ID(s) of the object(s) to retrieve.
1. $taxonomies (string|array)
The taxonomies to retrieve terms from.
2. $args — Optional. (array) => array()
Array of arguments.

Options

  • orderby (string) => 'name'

    Field by which results should be sorted. Accepts name,, count., slug, term_group, term_order, taxonomy, parent, or term_taxonomy_id.

  • order (string) => 'ASC'

    Sort order. Accepts ASC or DESC..

  • fields (string) => ''

    Fields to return for matched terms. Accepts all,, ids., names , and all_with_object_id. Note that all, or all_with_object_id will result in an array of term objects being returned, ids. will return an array of integers, and names an array of strings.

  • parent (int) => 0

    Limit results to the direct children of a given term ID.

  • update_term_meta_cache (bool) => true

    Whether to prime termmeta cache for matched terms. Only applies when $fields is all,, all_with_object_id., or term_id.

array(

    /**
     * Field by which results should be sorted. Accepts 'name', 'count', 'slug', 'term_group',
     * 'term_order', 'taxonomy', 'parent', or 'term_taxonomy_id'.
     *
     * @type string
     * @default 'name'
     */
    'orderby' => 'name',

    /**
     * Sort order. Accepts 'ASC' or 'DESC'.
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * Fields to return for matched terms. Accepts 'all', 'ids', 'names', and
     * 'all_with_object_id'. Note that 'all' or 'all_with_object_id' will result in an array of
     * term objects being returned, 'ids' will return an array of integers, and 'names' an array of
     * strings.
     *
     * @type string
     * @default ''
     */
    'fields' => '',

    /**
     * Optional. Limit results to the direct children of a given term ID.
     *
     * @type int
     * @optional
     */
    'parent' => 0,

    /**
     * Whether to prime termmeta cache for matched terms. Only applies when `$fields` is 'all',
     * 'all_with_object_id', or 'term_id'.
     *
     * @type bool
     * @default true
     */
    'update_term_meta_cache' => true
);        


Usage

  1. if ( !function_exists( 'wp_get_object_terms' ) ) { 
  2. require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3.  
  4. // The ID(s) of the object(s) to retrieve. 
  5. $object_ids = null; 
  6.  
  7. // The taxonomies to retrieve terms from. 
  8. $taxonomies = null; 
  9.  
  10. // Array of arguments. 
  11. $args = array( 
  12. 'orderby' => 'name', 
  13. 'order' => 'ASC', 
  14. 'fields' => '', 
  15. 'parent' => 0, 
  16. 'update_term_meta_cache' => true 
  17. ); 
  18.  
  19. // NOTICE! Understand what this does before running. 
  20. $result = wp_get_object_terms($object_ids, $taxonomies, $args); 
  21.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/taxonomy.php  
  1. function wp_get_object_terms($object_ids, $taxonomies, $args = array()) { 
  2. global $wpdb; 
  3.  
  4. if ( empty( $object_ids ) || empty( $taxonomies ) ) 
  5. return array(); 
  6.  
  7. if ( !is_array($taxonomies) ) 
  8. $taxonomies = array($taxonomies); 
  9.  
  10. foreach ( $taxonomies as $taxonomy ) { 
  11. if ( ! taxonomy_exists($taxonomy) ) 
  12. return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) ); 
  13.  
  14. if ( !is_array($object_ids) ) 
  15. $object_ids = array($object_ids); 
  16. $object_ids = array_map('intval', $object_ids); 
  17.  
  18. $defaults = array( 
  19. 'orderby' => 'name',  
  20. 'order' => 'ASC',  
  21. 'fields' => 'all',  
  22. 'parent' => '',  
  23. 'update_term_meta_cache' => true,  
  24. 'meta_query' => '',  
  25. ); 
  26. $args = wp_parse_args( $args, $defaults ); 
  27.  
  28. $terms = array(); 
  29. if ( count($taxonomies) > 1 ) { 
  30. foreach ( $taxonomies as $index => $taxonomy ) { 
  31. $t = get_taxonomy($taxonomy); 
  32. if ( isset($t->args) && is_array($t->args) && $args != array_merge($args, $t->args) ) { 
  33. unset($taxonomies[$index]); 
  34. $terms = array_merge($terms, wp_get_object_terms($object_ids, $taxonomy, array_merge($args, $t->args))); 
  35. } else { 
  36. $t = get_taxonomy($taxonomies[0]); 
  37. if ( isset($t->args) && is_array($t->args) ) 
  38. $args = array_merge($args, $t->args); 
  39.  
  40. $orderby = $args['orderby']; 
  41. $order = $args['order']; 
  42. $fields = $args['fields']; 
  43.  
  44. if ( in_array( $orderby, array( 'term_id', 'name', 'slug', 'term_group' ) ) ) { 
  45. $orderby = "t.$orderby"; 
  46. } elseif ( in_array( $orderby, array( 'count', 'parent', 'taxonomy', 'term_taxonomy_id' ) ) ) { 
  47. $orderby = "tt.$orderby"; 
  48. } elseif ( 'term_order' === $orderby ) { 
  49. $orderby = 'tr.term_order'; 
  50. } elseif ( 'none' === $orderby ) { 
  51. $orderby = ''; 
  52. $order = ''; 
  53. } else { 
  54. $orderby = 't.term_id'; 
  55.  
  56. // tt_ids queries can only be none or tr.term_taxonomy_id 
  57. if ( ('tt_ids' == $fields) && !empty($orderby) ) 
  58. $orderby = 'tr.term_taxonomy_id'; 
  59.  
  60. if ( !empty($orderby) ) 
  61. $orderby = "ORDER BY $orderby"; 
  62.  
  63. $order = strtoupper( $order ); 
  64. if ( '' !== $order && ! in_array( $order, array( 'ASC', 'DESC' ) ) ) 
  65. $order = 'ASC'; 
  66.  
  67. $taxonomy_array = $taxonomies; 
  68. $object_id_array = $object_ids; 
  69. $taxonomies = "'" . implode("', '", array_map( 'esc_sql', $taxonomies ) ) . "'"; 
  70. $object_ids = implode(', ', $object_ids); 
  71.  
  72. $select_this = ''; 
  73. if ( 'all' == $fields ) { 
  74. $select_this = 't.*, tt.*'; 
  75. } elseif ( 'ids' == $fields ) { 
  76. $select_this = 't.term_id'; 
  77. } elseif ( 'names' == $fields ) { 
  78. $select_this = 't.name'; 
  79. } elseif ( 'slugs' == $fields ) { 
  80. $select_this = 't.slug'; 
  81. } elseif ( 'all_with_object_id' == $fields ) { 
  82. $select_this = 't.*, tt.*, tr.object_id'; 
  83.  
  84. $where = array( 
  85. "tt.taxonomy IN ($taxonomies)",  
  86. "tr.object_id IN ($object_ids)",  
  87. ); 
  88.  
  89. if ( '' !== $args['parent'] ) { 
  90. $where[] = $wpdb->prepare( 'tt.parent = %d', $args['parent'] ); 
  91.  
  92. // Meta query support. 
  93. $meta_query_join = ''; 
  94. if ( ! empty( $args['meta_query'] ) ) { 
  95. $mquery = new WP_Meta_Query( $args['meta_query'] ); 
  96. $mq_sql = $mquery->get_sql( 'term', 't', 'term_id' ); 
  97.  
  98. $meta_query_join .= $mq_sql['join']; 
  99.  
  100. // Strip leading AND. 
  101. $where[] = preg_replace( '/^\s*AND/', '', $mq_sql['where'] ); 
  102.  
  103. $where = implode( ' AND ', $where ); 
  104.  
  105. $query = "SELECT $select_this FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON tt.term_id = t.term_id INNER JOIN $wpdb->term_relationships AS tr ON tr.term_taxonomy_id = tt.term_taxonomy_id $meta_query_join WHERE $where $orderby $order"; 
  106.  
  107. $objects = false; 
  108. if ( 'all' == $fields || 'all_with_object_id' == $fields ) { 
  109. $_terms = $wpdb->get_results( $query ); 
  110. $object_id_index = array(); 
  111. foreach ( $_terms as $key => $term ) { 
  112. $term = sanitize_term( $term, $taxonomy, 'raw' ); 
  113. $_terms[ $key ] = $term; 
  114.  
  115. if ( isset( $term->object_id ) ) { 
  116. $object_id_index[ $key ] = $term->object_id; 
  117.  
  118. update_term_cache( $_terms ); 
  119. $_terms = array_map( 'get_term', $_terms ); 
  120.  
  121. // Re-add the object_id data, which is lost when fetching terms from cache. 
  122. if ( 'all_with_object_id' === $fields ) { 
  123. foreach ( $_terms as $key => $_term ) { 
  124. if ( isset( $object_id_index[ $key ] ) ) { 
  125. $_term->object_id = $object_id_index[ $key ]; 
  126.  
  127. $terms = array_merge( $terms, $_terms ); 
  128. $objects = true; 
  129.  
  130. } elseif ( 'ids' == $fields || 'names' == $fields || 'slugs' == $fields ) { 
  131. $_terms = $wpdb->get_col( $query ); 
  132. $_field = ( 'ids' == $fields ) ? 'term_id' : 'name'; 
  133. foreach ( $_terms as $key => $term ) { 
  134. $_terms[$key] = sanitize_term_field( $_field, $term, $term, $taxonomy, 'raw' ); 
  135. $terms = array_merge( $terms, $_terms ); 
  136. } elseif ( 'tt_ids' == $fields ) { 
  137. $terms = $wpdb->get_col("SELECT tr.term_taxonomy_id FROM $wpdb->term_relationships AS tr INNER JOIN $wpdb->term_taxonomy AS tt ON tr.term_taxonomy_id = tt.term_taxonomy_id WHERE tr.object_id IN ($object_ids) AND tt.taxonomy IN ($taxonomies) $orderby $order"); 
  138. foreach ( $terms as $key => $tt_id ) { 
  139. $terms[$key] = sanitize_term_field( 'term_taxonomy_id', $tt_id, 0, $taxonomy, 'raw' ); // 0 should be the term id, however is not needed when using raw context. 
  140.  
  141. // Update termmeta cache, if necessary. 
  142. if ( $args['update_term_meta_cache'] && ( 'all' === $fields || 'all_with_object_id' === $fields || 'ids' === $fields ) ) { 
  143. if ( 'ids' === $fields ) { 
  144. $term_ids = $terms; 
  145. } else { 
  146. $term_ids = wp_list_pluck( $terms, 'term_id' ); 
  147.  
  148. update_termmeta_cache( $term_ids ); 
  149.  
  150. if ( ! $terms ) { 
  151. $terms = array(); 
  152. } elseif ( $objects && 'all_with_object_id' !== $fields ) { 
  153. $_tt_ids = array(); 
  154. $_terms = array(); 
  155. foreach ( $terms as $term ) { 
  156. if ( in_array( $term->term_taxonomy_id, $_tt_ids ) ) { 
  157. continue; 
  158.  
  159. $_tt_ids[] = $term->term_taxonomy_id; 
  160. $_terms[] = $term; 
  161. $terms = $_terms; 
  162. } elseif ( ! $objects ) { 
  163. $terms = array_values( array_unique( $terms ) ); 
  164.  
  165. /** 
  166. * Filters the terms for a given object or objects. 
  167. * @since 4.2.0 
  168. * @param array $terms An array of terms for the given object or objects. 
  169. * @param array $object_id_array Array of object IDs for which `$terms` were retrieved. 
  170. * @param array $taxonomy_array Array of taxonomies from which `$terms` were retrieved. 
  171. * @param array $args An array of arguments for retrieving terms for the given 
  172. * object(s). See wp_get_object_terms() for details. 
  173. */ 
  174. $terms = apply_filters( 'get_object_terms', $terms, $object_id_array, $taxonomy_array, $args ); 
  175.  
  176. /** 
  177. * Filters the terms for a given object or objects. 
  178. * The `$taxonomies` parameter passed to this filter is formatted as a SQL fragment. The 
  179. * {@see 'get_object_terms'} filter is recommended as an alternative. 
  180. * @since 2.8.0 
  181. * @param array $terms An array of terms for the given object or objects. 
  182. * @param int|array $object_ids Object ID or array of IDs. 
  183. * @param string $taxonomies SQL-formatted (comma-separated and quoted) list of taxonomy names. 
  184. * @param array $args An array of arguments for retrieving terms for the given object(s). 
  185. * See wp_get_object_terms() for details. 
  186. */ 
  187. return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );