get_term_by() WordPress Function
The get_term_by() function is a powerful tool for retrieving information about terms in your WordPress site. It can be used to get information about a specific term by its ID, slug, or name. Additionally, you can specify the taxonomy that the term belongs to. This function is often used in conjunction with the get_terms() function.
get_term_by( string $field, string|int $value, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ) #
Gets all term data from database by term field and data.
Description
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.
See also
- sanitize_term_field(): The $context param lists the available values for get_term_by() $filter param.
Parameters
- $field
(string)(Required)Either 'slug', 'name', 'term_id' (or 'id', 'ID'), or 'term_taxonomy_id'.
- $value
(string|int)(Required)Search for this term value.
- $taxonomy
(string)(Optional)Taxonomy name. Optional, if
$field
is 'term_taxonomy_id'.Default value: ''
- $output
(string)(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 value: OBJECT
- $filter
(string)(Optional) How to sanitize term fields.
Default value: 'raw'
Return
(WP_Term|array|false) WP_Term instance (or array) on success, depending on the $output
value. False if $taxonomy
does not exist or $term
was not found.
Source
File: wp-includes/taxonomy.php
function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) { // 'term_taxonomy_id' lookups don't require taxonomy checks. if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) { return false; } // No need to perform a query for empty 'slug' or 'name'. if ( 'slug' === $field || 'name' === $field ) { $value = (string) $value; if ( 0 === strlen( $value ) ) { return false; } } if ( 'id' === $field || 'ID' === $field || 'term_id' === $field ) { $term = get_term( (int) $value, $taxonomy, $output, $filter ); if ( is_wp_error( $term ) || null === $term ) { $term = false; } return $term; } $args = array( 'get' => 'all', 'number' => 1, 'taxonomy' => $taxonomy, 'update_term_meta_cache' => false, 'orderby' => 'none', 'suppress_filter' => true, ); switch ( $field ) { case 'slug': $args['slug'] = $value; break; case 'name': $args['name'] = $value; break; case 'term_taxonomy_id': $args['term_taxonomy_id'] = $value; unset( $args['taxonomy'] ); break; default: return false; } $terms = get_terms( $args ); if ( is_wp_error( $terms ) || empty( $terms ) ) { return false; } $term = array_shift( $terms ); // 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; } return get_term( $term, $taxonomy, $output, $filter ); }
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
Version | Description |
---|---|
5.5.0 | Added 'ID' as an alias of 'id' for the $field parameter. |
4.4.0 | $taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT . |
2.3.0 | Introduced. |