get_term_by( string $field, string|int $value, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ): WP_Term|array|false
- Since
- 2.3.0, 4.4.0, 5.5.0
- Source
wp-includes/taxonomy.php:1099
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.
Compatibility
- WordPress
- since 5.5.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$fieldstring- Either 'slug', 'name', 'term_id' (or 'id', 'ID'), or 'term_taxonomy_id'.
$valuestring|int- Search for this term value.
$taxonomystringoptional- Taxonomy name. Optional, if
$fieldis 'term_taxonomy_id'.Default:'' $outputstringoptional- 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.Default:
OBJECT $filterstringoptional- How to sanitize term fields. Default 'raw'.Default:
'raw'
Return value
WP_Term|array|false- WP_Term instance (or array) on success, depending on the
$outputvalue.
False if$taxonomydoes not exist or$termwas not found.
Performance profile
How much work a call to get_term_by() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Heavy
- Scaling
- Constant
- Instructions
- 12–69
- Plugin surface
- None
- Called by
- 20
Reaches the database via get_term().
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 96.
Nothing here hands control to plugin code.
20 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- querycontent query
get_term()called directly - hookthird-party callbacks
apply_filters()one call below get_term_by()
Further down the call graph this can also reach option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 8 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_term_by() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
$field !== "term_taxonomy_id" | 12–41 | taxonomy_exists() |
$field === "term_taxonomy_id" | 15–37 | none |
$field === "term_taxonomy_id" | 27–38 | get_term(), is_wp_error() |
$field !== "term_taxonomy_id" && taxonomy_exists() | 31–42 | taxonomy_exists(), get_term(), is_wp_error() |
$field === "term_taxonomy_id" && $field !== "id" && $field !== "ID" && $field !== "term_id" | 37–51 | get_terms(), is_wp_error() |
$field !== "term_taxonomy_id" && taxonomy_exists() && $field !== "id" && $field !== "ID" && $field !== "term_id" | 41–55 | taxonomy_exists(), get_terms(), is_wp_error() |
$field === "term_taxonomy_id" && $field !== "id" && $field !== "ID" && $field !== "term_id" && !is_wp_error() && !empty($terms) | 51–65 | get_terms(), is_wp_error(), array_shift(), get_term() |
$field !== "term_taxonomy_id" && taxonomy_exists() && $field !== "id" && $field !== "ID" && $field !== "term_id" && !is_wp_error() && !empty($terms) | 55–69 | taxonomy_exists(), get_terms(), is_wp_error(), array_shift(), get_term() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 96 | 12–69 | 17 | |
| 8.5 | 96 | 12–69 | 17 | |
| 8.4 | 96 | 12–69 | 17 | |
| 8.3 | 96 | 12–69 | 17 | |
| 8.2 | 96 | 12–69 | 17 | |
| 8.1 | 96 | 12–69 | 17 | 1 more instruction than PHP 7.4 |
| 7.4 | 95 | 12–69 | 17 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 4
- taxonomy_exists()Determines whether the taxonomy name exists.
- get_term()Gets all term data from database by term ID.
- is_wp_error()Checks whether the given variable is a WordPress Error.
- get_terms()Retrieves the terms in a given taxonomy or list of taxonomies.
Used by · 20
- Featured_Content::get_featured_post_ids()Get featured post IDs
- Featured_Content::validate_settings()Validate featured content settings.
- WP_Query::get_posts()Retrieves an array of posts based on query variables.
- WP_Query::get_queried_object()Retrieves the currently queried object.
- WP_REST_Menus_Controller::create_item()Creates a single term in a taxonomy.
- _wp_preview_terms_filter()Filters terms lookup to set the post format.
- get_bookmarks()Retrieves the list of bookmarks.
- get_cat_ID()Retrieves the ID of a category from its name.
- get_category_by_slug()Retrieves a category object by category slug.
- get_linkobjectsbyname()Gets an array of link objects associated with category $cat_name.
- get_linksbyname()Gets the links associated with category $cat_name.
- get_post_format_link()Returns a link to a post format index.
Show all 20
- get_term_link()Generates a permalink for a taxonomy term archive.
- upgrade_350()Execute changes made in WordPress 3.5.
- wp_get_nav_menu_object()Returns a navigation menu object.
- wp_insert_term()Adds a new term to the database.
- wp_unique_term_slug()Makes term slug unique, if it isn't already.
- wp_update_nav_menu_object()Saves the properties of a menu or create a new menu with those properties.
- wp_update_term()Updates term based on arguments provided.
- wp_xmlrpc_server::_insert_post()Helper method for wp_newPost() and wp_editPost(), containing shared logic.
Source code
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 );}Changelog
Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$field parameter.from the docblock$taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 6.7.7 tag, from
src/wp-includes/taxonomy.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.