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

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. $tax_clause = $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy ); 
  9.  
  10. if ( 'slug' == $field ) { 
  11. $_field = 't.slug'; 
  12. $value = sanitize_title($value); 
  13. if ( empty($value) ) 
  14. return false; 
  15. } elseif ( 'name' == $field ) { 
  16. // Assume already escaped 
  17. $value = wp_unslash($value); 
  18. $_field = 't.name'; 
  19. } elseif ( 'term_taxonomy_id' == $field ) { 
  20. $value = (int) $value; 
  21. $_field = 'tt.term_taxonomy_id'; 
  22.  
  23. // No `taxonomy` clause when searching by 'term_taxonomy_id'. 
  24. $tax_clause = ''; 
  25. } else { 
  26. $term = get_term( (int) $value, $taxonomy, $output, $filter ); 
  27. if ( is_wp_error( $term ) || is_null( $term ) ) { 
  28. $term = false; 
  29. return $term; 
  30.  
  31. $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" ); 
  32. if ( ! $term ) 
  33. return false; 
  34.  
  35. // In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the db. 
  36. if ( 'term_taxonomy_id' === $field ) { 
  37. $taxonomy = $term->taxonomy; 
  38.  
  39. wp_cache_add( $term->term_id, $term, 'terms' ); 
  40.  
  41. return get_term( $term, $taxonomy, $output, $filter );