get_term( int|WP_Term|object $term, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ): WP_Term|array|WP_Error|null

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$termint|WP_Term|object

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.

$taxonomystringoptional

Taxonomy name that $term is part of.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|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.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

$news = get_term_by( 'slug', 'news', 'category' );

if ( $news ) {
	$term_array = get_term( $news->term_id, 'category', ARRAY_A );
	echo '<pre>' . esc_html( print_r( $term_array, true ) ) . '</pre>';
} else {
	echo esc_html( 'Category "news" was not found.' );
}

$featured = get_term_by( 'slug', 'featured', 'post_tag' );

// An unregistered taxonomy name makes get_term() return a WP_Error.
$bad_taxonomy = get_term( $featured->term_id, 'not_a_real_taxonomy' );

// 'category' is a real, registered taxonomy, but this term isn't in it,
// so get_term() returns null instead of an error.
$wrong_taxonomy = get_term( $featured->term_id, 'category' );

echo esc_html( 'Unregistered taxonomy result: ' . ( is_wp_error( $bad_taxonomy ) ? $bad_taxonomy->get_error_message() : 'not an error' ) ) . '<br>';
echo esc_html( 'Mismatched taxonomy result: ' . ( is_null( $wrong_taxonomy ) ? 'null' : 'unexpected value' ) );

Common problems and fixes · 4

• Why do I get null sometimes and a WP_Error other times?
• Why does get_term() fail even though the taxonomy is definitely registered?
• Why does passing 0 or an empty string as the term always fail?
• Why does the returned term contain unescaped HTML in the name or description?

Alternatives and related functions

get_term_by

When you have a term's slug, name, or another field instead of its numeric ID.

get_terms

When you need a list of multiple terms matching query arguments rather than a single known ID.

get_the_terms

When you need the terms attached to a specific post in a given taxonomy.

sanitize_term_field

When you need to sanitize a single term field for a particular context without re-fetching the whole term.

Performance profile

How much work a call to get_term() 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

Reaches the database via get_term().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

14–74

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 111.

Plugin surface

2 hooks

Third-party callbacks on 'get_term', 'get_{$taxonomy}' run inside this call, and their cost is not bounded by anything here.

Called by

50

50 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_term()this function does it
• hookthird-party callbacksapply_filters()called directly

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 · 44 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost get_term() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while get_term() runs, in this order:

1. 1
   apply_filters( get_term )filterline 1021 (+44 into the body)

   Filters a taxonomy term object.

2. 2
   apply_filters( get_{$taxonomy} )filterline 1040 (+63 into the body)

   Filters a taxonomy term object.

Uses · 8

• __()Retrieves the translation of $text.
• taxonomy_exists()Determines whether the taxonomy name exists.
• sanitize_term()Sanitizes all term fields.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• WP_Error::__construct()Initializes the error.
• WP_Term::__construct()Constructor.
• WP_Term::get_instance()Retrieve WP_Term instance.

Used by · 50

• WP_Links_List_Table::column_categories()Handles the link categories column output.
• WP_Query::get_queried_object()Retrieves the currently queried object.
• WP_REST_Menu_Items_Controller::prepare_item_for_database()Prepares a single nav menu item for create or update.
• WP_REST_Menus_Controller::update_item()Updates a single term from a taxonomy.
• WP_REST_Posts_Controller::check_assign_terms_permission()Checks whether current user can assign all terms sent with the current request.
• WP_REST_Term_Search_Handler::prepare_item()Prepares the search result for a given term ID.
• WP_REST_Term_Search_Handler::prepare_item_links()Prepares links for the search result of a given ID.
• WP_REST_Terms_Controller::create_item()Creates a single term in a taxonomy.
• WP_REST_Terms_Controller::get_term()Get the term, if the ID is valid.
• WP_REST_Terms_Controller::prepare_item_for_database()Prepares a single term for create or update.
• WP_REST_Terms_Controller::prepare_links()Prepares links for the request.
• WP_REST_Terms_Controller::update_item()Updates a single term from a taxonomy.

Source code

View on Trac ↗View on GitHub ↗

977function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {978	if ( empty( $term ) ) {979		return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );980	}981 982	if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {983		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );984	}985 986	if ( $term instanceof WP_Term ) {987		$_term = $term;988	} elseif ( is_object( $term ) ) {989		if ( empty( $term->filter ) || 'raw' === $term->filter ) {990			$_term = sanitize_term( $term, $taxonomy, 'raw' );991			$_term = new WP_Term( $_term );992		} else {993			$_term = WP_Term::get_instance( $term->term_id );994		}995	} else {996		$_term = WP_Term::get_instance( $term, $taxonomy );997	}998 999	if ( is_wp_error( $_term ) ) {1000		return $_term;1001	} elseif ( ! $_term ) {1002		return null;1003	}1004 1005	// Ensure for filters that this is not empty.1006	$taxonomy = $_term->taxonomy;1007 1008	$old_term = $_term;1009	/**1010	 * Filters a taxonomy term object.1011	 *1012	 * The {@see 'get_$taxonomy'} hook is also available for targeting a specific1013	 * taxonomy.1014	 *1015	 * @since 2.3.01016	 * @since 4.4.0 `$_term` is now a `WP_Term` object.1017	 *1018	 * @param WP_Term $_term    Term object.1019	 * @param string  $taxonomy The taxonomy slug.1020	 */1021	$_term = apply_filters( 'get_term', $_term, $taxonomy );1022 1023	/**1024	 * Filters a taxonomy term object.1025	 *1026	 * The dynamic portion of the hook name, `$taxonomy`, refers1027	 * to the slug of the term's taxonomy.1028	 *1029	 * Possible hook names include:1030	 *1031	 *  - `get_category`1032	 *  - `get_post_tag`1033	 *1034	 * @since 2.3.01035	 * @since 4.4.0 `$_term` is now a `WP_Term` object.1036	 *1037	 * @param WP_Term $_term    Term object.1038	 * @param string  $taxonomy The taxonomy slug.1039	 */1040	$_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );1041 1042	// Bail if a filter callback has changed the type of the `$_term` object.1043	if ( ! ( $_term instanceof WP_Term ) ) {1044		return $_term;1045	}1046 1047	// Sanitize term, according to the specified filter.1048	if ( $_term !== $old_term || $_term->filter !== $filter ) {1049		$_term->filter( $filter );1050	}1051 1052	if ( ARRAY_A === $output ) {1053		return $_term->to_array();1054	} elseif ( ARRAY_N === $output ) {1055		return array_values( $_term->to_array() );1056	}

Changelog

Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.8 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.