W3cubDocs

/WordPress

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

Get all Term data from database by Term ID.

Description

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’ as the filter name. Useful for custom taxonomies or plugging into default taxonomies.

See also

Parameters

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

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'

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.

Source

File: 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.
	 *
	 * @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 filter name, `$taxonomy`, refers
	 * to the slug of the term's 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_{$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;
}

Uses

Uses Description
wp-includes/class-wp-term.php: WP_Term::__construct()

Constructor.
wp-includes/class-wp-term.php: WP_Term::get_instance()

Retrieve WP_Term instance.
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/taxonomy.php: sanitize_term()

Sanitize Term all fields.
wp-includes/taxonomy.php: get_term

Filters a taxonomy term object.
wp-includes/taxonomy.php: get_{$taxonomy}

Filters a taxonomy term object.
wp-includes/taxonomy.php: taxonomy_exists()

Determines whether the taxonomy name exists.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.
wp-includes/load.php: is_wp_error()

Check whether variable is a WordPress Error.
wp-includes/class-wp-error.php: WP_Error::__construct()

Initialize the error.

Used By

Used By Description
wp-includes/rest-api.php: rest_get_route_for_term()

Gets the REST API route for a term.
wp-includes/meta.php: get_object_subtype()

Returns the object subtype for a given object ID of a specific type.
wp-includes/class-wp-term-query.php: WP_Term_Query::populate_terms()

Creates an array of term objects from an array of term IDs.
wp-includes/category-template.php: get_term_parents_list()

Retrieves term parents with separator.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::get_term()

Get the term, if the ID is valid.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::prepare_links()

Prepares links for the request.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::prepare_item_for_database()

Prepares a single term for create or update.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::create_item()

Creates a single term in a taxonomy.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::update_item()

Updates a single term from a taxonomy.
wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::check_assign_terms_permission()

Checks whether current user can assign all terms sent with the current request.
wp-includes/class-wp-term-query.php: WP_Term_Query::get_terms()

Get terms, based on query_vars.
wp-admin/includes/class-wp-links-list-table.php: WP_Links_List_Table::column_categories()

Handles the link categories column output.
wp-admin/includes/export.php: export_wp()

Generates the WXR export file for download.
wp-admin/includes/taxonomy.php: get_category_to_edit()

Get category object for given ID and ‘edit’ filter context.
wp-admin/includes/taxonomy.php: wp_update_category()

Aliases wp_insert_category() with minimal args.
wp-admin/includes/template.php: wp_terms_checklist()

Output an unordered list of checkbox input elements labelled with term names.
wp-admin/includes/ajax-actions.php: wp_ajax_add_menu_item()

Ajax handler for adding a menu item.
wp-admin/includes/ajax-actions.php: wp_ajax_inline_save_tax()

Ajax handler for quick edit saving for a term.
wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()

Ajax handler for adding a hierarchical term.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_tag()

Ajax handler for deleting a tag.
wp-admin/includes/ajax-actions.php: wp_ajax_add_tag()

Ajax handler to add a tag.
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::column_name()
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::_rows()
wp-admin/includes/class-walker-nav-menu-edit.php: Walker_Nav_Menu_Edit::start_el()

Start the element output.
wp-admin/includes/nav-menu.php: _wp_ajax_menu_quick_search()

Prints the appropriate response to a menu quick search.
wp-includes/capabilities.php: map_meta_cap()

Maps meta capabilities to primitive capabilities.
wp-includes/class-walker-category.php: Walker_Category::start_el()

Starts the element output.
wp-includes/category-template.php: get_the_category_by_ID()

Retrieves category name based on category ID.
wp-includes/class-wp-query.php: WP_Query::get_queried_object()

Retrieve queried object.
wp-includes/category.php: get_cat_name()

Retrieves the name of a category from its ID.
wp-includes/category.php: get_tag()

Retrieves a post tag by tag ID or tag object.
wp-includes/category.php: get_category()

Retrieves category data given a category ID or category object.
wp-includes/category.php: get_category_by_path()

Retrieves a category based on URL containing the category slug.
wp-includes/taxonomy.php: wp_get_term_taxonomy_parent_id()

Returns the term’s parent’s term_ID.
wp-includes/taxonomy.php: get_object_term_cache()

Retrieves the cached term objects for the given object ID.
wp-includes/taxonomy.php: _get_term_children()

Get the subset of $terms that are descendants of $term_id.
wp-includes/taxonomy.php: get_term_link()

Generate a permalink for a taxonomy term archive.
wp-includes/taxonomy.php: get_ancestors()

Get an array of ancestor IDs for a given object.
wp-includes/taxonomy.php: wp_unique_term_slug()

Will make slug unique, if it isn’t already.
wp-includes/taxonomy.php: wp_update_term()

Update term based on arguments provided.
wp-includes/taxonomy.php: wp_delete_term()

Removes a term from the database.
wp-includes/taxonomy.php: get_term_by()

Get all Term data from database by Term field and data.
wp-includes/taxonomy.php: get_term_field()

Get sanitized Term field.
wp-includes/taxonomy.php: get_term_to_edit()

Sanitizes Term for editing.
wp-includes/taxonomy.php: term_is_ancestor_of()

Check if a term is an ancestor of another term.
wp-includes/link-template.php: get_term_feed_link()

Retrieves the feed link for a term.
wp-includes/link-template.php: get_edit_term_link()

Retrieves the URL for editing a given term.
wp-includes/link-template.php: get_permalink()

Retrieves the full permalink for the current post or post ID.
wp-includes/nav-menu.php: wp_setup_nav_menu_item()

Decorates a menu item object with the shared navigation menu item properties.
wp-includes/nav-menu.php: wp_get_nav_menu_object()

Returns a navigation menu object.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_newTerm()

Create a new term.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_editTerm()

Edit a term.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_deleteTerm()

Delete a term.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::wp_getTerm()

Retrieve a term.

Changelog

Version Description
4.4.0 Converted to return a WP_Term object if $output is OBJECT. The $taxonomy parameter was made optional.
2.3.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/get_term