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.

Top ↑

See also


Top ↑

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'


Top ↑

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.


Top ↑

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


Top ↑

Changelog

Changelog
VersionDescription
5.5.0Added '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.0Introduced.

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More
Show More