get_term_by() │ WP 2.3.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.

Uses: get_terms(), get_term()

Used By: get_cat_ID(), get_category_by_slug(), wp_get_nav_menu_object()

1 time — 0.001272 sec (very slow) | 50000 times — 4.95 sec (fast) | PHP 7.1.11, WP 4.9.6

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', 'term_id' (or 'id', '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'

Examples

#1 Examples of how to get terms from different taxonomies

Examples to get terms by name and taxonomy type (taxonomy_name as category, post_tag or custom taxonomy).

// Let's get the "News" category by its name:
$term = get_term_by('name', 'News', 'category' );

// Get tags (post_tag taxonomy) by slug
$term = get_term_by( 'slug', 'my-tag-name', 'post_tag' );

// Get the term "News" from the taxonomy "my_custom_taxonomy" by its name:
$term = get_term_by( 'name', 'News', 'my_custom_taxonomy' );

// Retrieve a term by its id (term_id) from the taxonomy `category`.
get_term_by( 'id', 12, 'category' )

It is better to use the get_term() function to get the term by ID.

As a result of these examples, the variable $term will contain such an object:

stdClass Object
(
	[term_id] => 80
	[name] => My Category
	[slug] => my-category
	[term_group] => 0
	[term_taxonomy_id] => 87
	[taxonomy] => my_tax
	[description] =>
	[parent] => 0
	[count] => 5
)

#2 Obtaining the post category

This example shows how to get all the data of the first post category, using this function:

global $post;

// get all categories of the current post
$post_cats = get_the_category( $post->ID );

// collect data about all post categories in $cats_data
foreach ( $post_cats as $post_cat ) {
	$cats_data[] = get_term_by( 'id', $post_cat->cat_ID, 'category' );
}
// here $cats_data contains the data of all post categories

The first category of the post can be obtained as follows:

$first_cat = get_term_by( 'id', $post_cats[0]->cat_ID, 'category' );

This is a demo example. The idea is that get_the_category() returns an array with all category data and, for example, the first category data will be in the first element of the array: $post_cats[0].

#3 get_term_by() returns a single WP_Term object.

Because of core changes from v4.1 – 4.3, it’s now possible for multiple terms to match the supplied name or slug parameters.

The WP_Term Object returned will be the first matching term found by mySQL, there is no indication that other matching terms may exist. If there is any possibility of multiple terms having the same name or slug in your application, you should use get_terms() instead of get_term_by().

#4 Get custom taxonomy term

If you are using a custom taxonomy, this might not work unless you add the third parameter - taxonomy name:

My custom taxonomy is wpdocs_playlist.

$playlist = get_term_by( 'slug', $playlist_key, 'wpdocs_playlist' );

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.

`get_term_by() get term by` code ^{WP 6.1.1}

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 );
}