Function Reference/get term by

Languages: English • Español • term by 日本語 (Add your language)

1 Description
2 Usage
3 Parameters
4 Return Values
5 Examples
- 5.1 Wrong example in this page history
6 Notes
7 Change Log
8 Source File
9 Related

Description

Get all Term data from database by Term field and data.

Warning: $value is not HTML-escaped for the '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.

Usage

<?php get_term_by( $field, $value, $taxonomy, $output, $filter ) ?>

Parameters

$field

(string) (required) Either 'id', 'slug', 'name', or 'term_taxonomy_id'

Default:

$value

(string|integer) (required) Search for this term value

Default: None

$taxonomy

(string) (required) Taxonomy Name category, post_tag, link_category, nav_menu or something custom

Default: '' (empty string)

$output

(string) (optional) Constant OBJECT, ARRAY_A, or ARRAY_N

Default: OBJECT

$filter

(string) (optional) default is raw or no WordPress defined filter will applied.

Default: 'raw'

Return Values

(mixed): Term Row (object or array) from database. Will return false if $taxonomy does not exist or $term was not found. Othewise returns object (by default) or array of fields depending on $output parameter.

The fields returned are:

term_id (See warning below)
name
slug
term_group
term_taxonomy_id
taxonomy
description
parent
count

Warning: string vs integer confusion! Field values, including term_id are returned in string format. Before further use, typecast numeric values to actual integers, otherwise WordPress will mix up term_ids and slugs which happen to have only numeric characters!

Examples

Taxonomy_name is the name of taxonomy, not the term_name and is required; the id (term_id) is the ID of the term, not post_id;...

Remember:
↓ Taxonomy type (e.g. post_tag)
Terms in this taxonomy:
→ news
→ webdev
→ ...

Examples to get terms by name and taxonomy type (taxonomy_name as category, post_tag or custom taxonomy).

// Get term by name ''news'' in Categories taxonomy.
$category = get_term_by('name', 'news', 'category')

// Get term by name ''news'' in Tags taxonomy.
$tag = get_term_by('name', 'news', 'post_tag')

// Get term by name ''news'' in Custom taxonomy.
$term = get_term_by('name', 'news', 'my_custom_taxonomy')

// Get term by name ''Default Menu'' from theme's nav menus.
// (Alternative to using wp_get_nav_menu_items)
$menu = get_term_by('name', 'Default Menu', 'nav_menu');

By id (term_id, not post_id):

// Get term by id (''term_id'') in Categories taxonomy.
get_term_by('id', 12, 'category')

...

Wrong example in this page history

Warning: the example below is wrong (see in this page history):

get_term_by( 'id', (int) $post->ID, 'taxonomy_name' ); // return null

This example tries to get a term by ID (term_id) but uses a post ID instead of a term ID.

This example is the correct way to get the term(s) for a post using the post ID:

// get_term_by( 'id', $category_id, 'category' )
global $post;

$my_categories   = array();
$post_categories = get_the_category( $post->ID );

foreach ( $post_categories as $post_category ) {
	$my_categories[] = get_term_by( 'id', $post_category->cat_ID, 'category' );
}

// OR:
$my_category = get_term_by( 'id', $post_categories[0]->cat_ID, 'category' );

Notes

Warning: $value is not escaped for 'name' $field. You must do it yourself, if required.
See sanitize_term_field() The $context param lists the available values for 'get_term_by' $filter param.
Uses: sanitize_term() Cleanses the term based on $filter context before returning.
Uses global: (object) $wpdb
get_term_by() returns a single WP_Term object. Because of core changes from v4.1 - 4.3, it's now possible for multiple terms to match the supplied name or slug parameters. The WP_Term Object returned will be the first matching term found by mySQL, there is no indication that other matching terms may exist. If there is any possibility of multiple terms having the same name or slug in your application, you should use get_terms() instead of get_term_by().

Change Log

Since: 2.3.0

Source File

get_term_by() is located in wp-includes/taxonomy.php.

See also index of Function Reference and index of Template Tags.

WordPress.org

Codex