get_term_by() WP 1.0
Get all Term data from database by Term field and data.
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.
No Hooks.
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.
Usage
get_term_by( $field, $value, $taxonomy, $output, $filter );
- $field(string) (required)
- Either 'slug', 'name', 'id' or 'ID' (term_id), or 'term_taxonomy_id'.
- $value(string/int) (required)
- Search for this term value.
- $taxonomy(string)
- Taxonomy name. Optional, if $field is 'term_taxonomy_id'.
Default: '' - $output(string)
- 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 - $filter(string)
- How to sanitize term fields.
Default: 'raw'
Notes
- See: sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
Changelog
Since 2.3.0 | Introduced. |
Since 4.4.0 | $taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT. |
Since 5.5.0 | Added 'ID' as an alias of 'id' for the $field parameter. |
Code of get_term_by() get term by WP 5.6
Related Functions
From tag: Term (taxonomies terms)
- get_term()
- get_term_children()
- get_term_field()
- get_term_link()
- get_terms()
- get_the_term_list()
- get_the_terms()
More from category: Any taxonomy
- edit_term_link()
- get_edit_term_link()
- get_taxonomies()
- get_taxonomy()
- is_taxonomy_hierarchical()
- register_taxonomy()