get_term_by

Get all Term data from database by Term field and data.

Description

(WP_Term|array|false) get_term_by( (string) $field, (string|int) $value, (string) $taxonomy = '', (constant) $output = OBJECT, (string) $filter = 'raw' ); 

Warning: $value is not escaped for name $field. You must do it yourself, if required.

The default $field is id,, therefore it is possible to also use null for field, but not recommended that you do so.

If $value does not exist, the return value will be false. If $taxonomy exists and $field and $value combinations exist, the Term will be returned.

This function will always return the first term that matches the $field- '$value'-'$taxonomy' combination specified in the parameters. If your query is likely to match more than one term (as is likely to be the case when $field is name , for example), consider using get_terms(…) instead; that way, you will get all matching terms, and can provide your own logic for deciding which one was intended.

Returns (WP_Term|array|false)

WP_Term instance (or array) on success. Will return false if `$taxonomy` does not exist or `$term` was not found.

Parameters (5)

0. $field (string)
Either slug,, name , id (term_id), or term_taxonomy_id
1. $value (string|int)
Search for this term value
2. $taxonomy — Optional. (string) => ''
Taxonomy name. Optional, if $field is term_taxonomy_id..
3. $output — Optional. (constant) => OBJECT
The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
4. $filter — Optional. (string) => 'raw'
Optional, default is raw or no WordPress defined filter will applied.

Usage

  1. if ( !function_exists( 'get_term_by' ) ) { 
  2.     require_once ABSPATH . WPINC . '/taxonomy.php'; 
  3. } 
  4.   
  5. // Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id' 
  6. $field = ''; 
  7.   
  8. // Search for this term value 
  9. $value = null; 
  10.   
  11. // Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'. 
  12. $taxonomy = ''; 
  13.   
  14. // Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to 
  15. // a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT. 
  16. $output = OBJECT; 
  17.   
  18. // Optional, default is raw or no WordPress defined filter will applied. 
  19. $filter = 'raw'; 
  20.   
  21. // NOTICE! Understand what this does before running. 
  22. $result = get_term_by($field, $value, $taxonomy, $output, $filter); 
  23.     

Defined (1)

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

/wp-includes/taxonomy.php  
  1. function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) { 
  2.     global $wpdb; 
  3.  
  4.     // 'term_taxonomy_id' lookups don't require taxonomy checks. 
  5.     if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) { 
  6.         return false; 
  7.     } 
  8.  
  9.     $tax_clause = $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy ); 
  10.  
  11.     if ( 'slug' == $field ) { 
  12.         $_field = 't.slug'; 
  13.         $value = sanitize_title($value); 
  14.         if ( empty($value) ) 
  15.             return false; 
  16.     } elseif ( 'name' == $field ) { 
  17.         // Assume already escaped 
  18.         $value = wp_unslash($value); 
  19.         $_field = 't.name'; 
  20.     } elseif ( 'term_taxonomy_id' == $field ) { 
  21.         $value = (int) $value; 
  22.         $_field = 'tt.term_taxonomy_id'; 
  23.  
  24.         // No `taxonomy` clause when searching by 'term_taxonomy_id'. 
  25.         $tax_clause = ''; 
  26.     } else { 
  27.         $term = get_term( (int) $value, $taxonomy, $output, $filter ); 
  28.         if ( is_wp_error( $term ) || is_null( $term ) ) { 
  29.             $term = false; 
  30.         } 
  31.         return $term; 
  32.     } 
  33.  
  34.     $term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE $_field = %s", $value ) . " $tax_clause LIMIT 1" ); 
  35.     if ( ! $term ) 
  36.         return false; 
  37.  
  38.     // In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the db. 
  39.     if ( 'term_taxonomy_id' === $field ) { 
  40.         $taxonomy = $term->taxonomy; 
  41.     } 
  42.  
  43.     wp_cache_add( $term->term_id, $term, 'terms' ); 
  44.  
  45.     return get_term( $term, $taxonomy, $output, $filter ); 
  46. }