get_term() │ WP 2.3.0

Gets data about a taxonomy element (term) by the provided ID.

The function has two hooks:

get_term - triggers always (for all taxonomies).
get_(taxonomy) - dynamic hook where (taxonomy) is replaced with the name of the taxonomy. For example, for categories, the name of the hook will be term_category. It will trigger only for the specified taxonomy.

Both hooks receive two parameters: the term object (WP_Term) and the name of the taxonomy. Both hooks must return the term object.

The function caches the result, and when the same term is retrieved again, there is no database query - the result is simply returned from the cache.

To get a term by the field: name or slug, use get_term_by().

The function is identical to get_category(), except that in this function you can specify the name of the taxonomy to work with.

Uses: sanitize_term(). Cleans the element based on the filter rules specified in the $filter parameter.

Uses: WP_Term()

Used By: get_ancestors(), get_term_by(), get_category(), get_cat_name(), get_the_category_by_ID(), wp_get_term_taxonomy_parent_id(), wp_get_nav_menu_object()

1 time — 0.000125 sec (fast) | 50000 times — 0.42 sec (very fast) | PHP 7.1.2, WP 4.7.3

Hooks from the function

Returns

WP_Term|Array|WP_Error|null.

WP_Term (term object) — when the term is found and $output = OBJECT (default).
Array — when the term is found and $output = ARRAY_A or $output = ARRAY_N.
null — when the term is not found.
WP_Error (object) — when the taxonomy does not exist.

Usage

get_term( $term, $taxonomy, $output, $filter );

$term(number/object) (required)

If an ID is provided, the data will be retrieved from the database. If an object is provided, filters will be applied and the provided object will be returned.

$taxonomy(string)

The name of the taxonomy to which the element $term belongs.
Starting from version 4.4, this parameter became optional.
Default: ''

$output(string)

What type of array to return the data:

OBJECT - object.
ARRAY_A - associative array.
ARRAY_N - indexed array.

Default: OBJECT

$filter(string)

How to clean the fields of the array before returning.
Default: 'raw'

Examples

#1 Let's get the data about the taxonomy element from the database:

$term_id = 65;
$taxonomy = 'my_taxonomy'; // Since version 4.4 this parameter is no longer required.
$term = get_term( $term_id, $taxonomy );
// Now, the variable contains data about the taxonomy element.

// An alternative name for the element can be found here
$slug = $term->slug;

// Item name
$name = $term->name;

// And this is how we get a description of an element of the taxonomy
$desc = $term->description;

#2 Obtaining a taxonomy element without specifying a taxonomy name

Since version 4.4 it is now possible not to specify the $taxonomy parameter:

$term = get_term( 562 );
print_r( $term );

/* Will withdraw:
WP_Term Object
(
	[term_id] => 562
	[name] => Records
	[slug] => zapisi
	[term_group] => 0
	[term_taxonomy_id] => 582
	[taxonomy] => my_taxonomy_name
	[description] =>
	[parent] => 0
	[count] => 1
	[filter] => raw
)
*/

#3 Example of how this function works with cache

get_term() utilizes the WP Object Cache to store previously-fetched term data. This helps avoid subsequent data I/O calls from the database to read term data. For example:

$term = get_term( 1 , 'store' );
echo $term->name;

$term = get_term( 1 , 'store' );
echo $term->slug;

This example will only perform a single select query on the database. The second get_term will use the WP Object Cache to fetch the previous term object from memory.

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	Converted to return a WP_Term object if `$output` is `OBJECT`. The `$taxonomy` parameter was made optional.

`get_term() get term` code ^{WP 6.8.3}

wp-includes/taxonomy.php

function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
	if ( empty( $term ) ) {
		return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
	}

	if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}

	if ( $term instanceof WP_Term ) {
		$_term = $term;
	} elseif ( is_object( $term ) ) {
		if ( empty( $term->filter ) || 'raw' === $term->filter ) {
			$_term = sanitize_term( $term, $taxonomy, 'raw' );
			$_term = new WP_Term( $_term );
		} else {
			$_term = WP_Term::get_instance( $term->term_id );
		}
	} else {
		$_term = WP_Term::get_instance( $term, $taxonomy );
	}

	if ( is_wp_error( $_term ) ) {
		return $_term;
	} elseif ( ! $_term ) {
		return null;
	}

	// Ensure for filters that this is not empty.
	$taxonomy = $_term->taxonomy;

	$old_term = $_term;
	/**
	 * Filters a taxonomy term object.
	 *
	 * The {@see 'get_$taxonomy'} hook is also available for targeting a specific
	 * taxonomy.
	 *
	 * @since 2.3.0
	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
	 *
	 * @param WP_Term $_term    Term object.
	 * @param string  $taxonomy The taxonomy slug.
	 */
	$_term = apply_filters( 'get_term', $_term, $taxonomy );

	/**
	 * Filters a taxonomy term object.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers
	 * to the slug of the term's taxonomy.
	 *
	 * Possible hook names include:
	 *
	 *  - `get_category`
	 *  - `get_post_tag`
	 *
	 * @since 2.3.0
	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
	 *
	 * @param WP_Term $_term    Term object.
	 * @param string  $taxonomy The taxonomy slug.
	 */
	$_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );

	// Bail if a filter callback has changed the type of the `$_term` object.
	if ( ! ( $_term instanceof WP_Term ) ) {
		return $_term;
	}

	// Sanitize term, according to the specified filter.
	if ( $_term !== $old_term || $_term->filter !== $filter ) {
		$_term->filter( $filter );
	}

	if ( ARRAY_A === $output ) {
		return $_term->to_array();
	} elseif ( ARRAY_N === $output ) {
		return array_values( $_term->to_array() );
	}

	return $_term;
}