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
if ( !function_exists( 'get_term_by' ) ) { require_once ABSPATH . WPINC . '/taxonomy.php'; } // Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id' $field = ''; // Search for this term value $value = null; // Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'. $taxonomy = ''; // Optional. 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. $output = OBJECT; // Optional, default is raw or no WordPress defined filter will applied. $filter = 'raw'; // NOTICE! Understand what this does before running. $result = get_term_by($field, $value, $taxonomy, $output, $filter);
Defined (1)
The function is defined in the following location(s).
- /wp-includes/taxonomy.php
- function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
- global $wpdb;
- // 'term_taxonomy_id' lookups don't require taxonomy checks.
- if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) {
- return false;
- }
- $tax_clause = $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy );
- if ( 'slug' == $field ) {
- $_field = 't.slug';
- $value = sanitize_title($value);
- if ( empty($value) )
- return false;
- } elseif ( 'name' == $field ) {
- // Assume already escaped
- $value = wp_unslash($value);
- $_field = 't.name';
- } elseif ( 'term_taxonomy_id' == $field ) {
- $value = (int) $value;
- $_field = 'tt.term_taxonomy_id';
- // No `taxonomy` clause when searching by 'term_taxonomy_id'.
- $tax_clause = '';
- } else {
- $term = get_term( (int) $value, $taxonomy, $output, $filter );
- if ( is_wp_error( $term ) || is_null( $term ) ) {
- $term = false;
- }
- return $term;
- }
- $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" );
- if ( ! $term )
- return false;
- // In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the db.
- if ( 'term_taxonomy_id' === $field ) {
- $taxonomy = $term->taxonomy;
- }
- wp_cache_add( $term->term_id, $term, 'terms' );
- return get_term( $term, $taxonomy, $output, $filter );
- }