get_term() │ WP 2.3.0

Get all Term data from database by Term ID.

The usage of the get_term function is to apply filters to a term object. It is possible to get a term object from the database before applying the filters.

$term ID must be part of $taxonomy, to get from the database. Failure, might be able to be captured by the hooks. Failure would be the same value as $wpdb returns for the get_row method.

There are two hooks, one is specifically for each term, named get_term, and the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the term object, and the taxonomy name as parameters. Both hooks are expected to return a term object.

get_term hook - Takes two parameters the term Object and the taxonomy name. Must return term object. Used in get_term() as a catch-all filter for every $term.

get_(taxonomy) hook - Takes two parameters the term Object and the taxonomy name. Must return term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be get_category the filter name. Useful for custom taxonomies or plugging into default taxonomies.

Uses: WP_Term()

Used By: get_ancestors(), get_term_by(), get_cat_name(), get_category(), 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

Return

WP_Term|Array|WP_Error|null. WP_Term instance (or array) on success, depending on the $output value. WP_Error if $taxonomy does not exist. Null for miscellaneous failure.

Usage

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

$term(int|WP_Term|object) (required): If integer, term data will be fetched from the database, or from the cache if available. If stdClass object (as in the results of a database query), will apply filters and return a WP_Term object with the $term data. If WP_Term, will return $term.
$taxonomy(string): Taxonomy name that $term is part of.
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 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.

Code of `get_term() get term` ^{WP 6.0}

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;

	/**
	 * 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.
	$_term->filter( $filter );

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

	return $_term;
}