Question

get_term_by( string $field,  string|int $value,  string $taxonomy = '',  string $output = OBJECT,  string $filter = 'raw' )

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

---

description

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

This function will always return the first term that matches the $field– $value–$taxonomy combination specified in the parameters. If your query is likely to match more than one term (as is likely to be the case when $field is ‘name’, for example), consider using get_terms() instead; that way, you will get all matching terms, and can provide your own logic for deciding which one was intended.

---

参数

$field

(string) (Required) Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'

$value

(string|int) (Required) Search for this term value

$taxonomy

(string) (Optional) Taxonomy name. Optional, if $field is 'term_taxonomy_id'.

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) default is raw or no WordPress defined filter will applied.

Default value: 'raw'

---

返回值

(WP_Term|array|false) WP_Term instance (or array) on success. Will return false if $taxonomy does not exist or $term was not found.

---

源代码

File: wp-includes/taxonomy.php

function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {

	// 'term_taxonomy_id' lookups don't require taxonomy checks.
	if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) {
		return false;
	}

	// No need to perform a query for empty 'slug' or 'name'.
	if ( 'slug' === $field || 'name' === $field ) {
		$value = (string) $value;

		if ( 0 === strlen( $value ) ) {
			return false;
		}
	}

	if ( 'id' === $field || 'term_id' === $field ) {
		$term = get_term( (int) $value, $taxonomy, $output, $filter );
		if ( is_wp_error( $term ) || null === $term ) {
			$term = false;
		}
		return $term;
	}

	$args = array(
		'get'                    => 'all',
		'number'                 => 1,
		'taxonomy'               => $taxonomy,
		'update_term_meta_cache' => false,
		'orderby'                => 'none',
		'suppress_filter'        => true,
	);

	switch ( $field ) {
		case 'slug' :
			$args['slug'] = $value;
			break;
		case 'name' :
			$args['name'] = $value;
			break;
		case 'term_taxonomy_id' :
			$args['term_taxonomy_id'] = $value;
			unset( $args[ 'taxonomy' ] );
			break;
		default :
			return false;
	}

	$terms = get_terms( $args );
	if ( is_wp_error( $terms ) || empty( $terms ) ) {
		return false;
	}

	$term = array_shift( $terms );

	// In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the db.
	if ( 'term_taxonomy_id' === $field ) {
		$taxonomy = $term->taxonomy;
	}

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

---

更新日志

Version	description
4.4.0	$taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT.
2.3.0	Introduced.

---

相关函数

Uses

• wp-includes/taxonomy.php: get_terms()
• wp-includes/taxonomy.php: taxonomy_exists()
• wp-includes/taxonomy.php: get_term()
• wp-includes/load.php: is_wp_error()

---

Used By

• wp-includes/deprecated.php: get_linksbyname()
• wp-includes/deprecated.php: get_linkobjectsbyname()
• wp-includes/class-wp-query.php: WP_Query::get_queried_object()
• wp-includes/class-wp-query.php: WP_Query::get_posts()
• wp-includes/category.php: get_category_by_slug()
• wp-includes/category.php: get_cat_ID()
• wp-includes/taxonomy.php: get_term_link()
• wp-includes/taxonomy.php: wp_unique_term_slug()
• wp-includes/taxonomy.php: wp_update_term()
• wp-includes/taxonomy.php: wp_insert_term()
• wp-includes/revision.php: _wp_preview_terms_filter()
• wp-includes/bookmark.php: get_bookmarks()
• wp-includes/post-formats.php: get_post_format_link()
• wp-includes/nav-menu.php: wp_update_nav_menu_object()
• wp-includes/nav-menu.php: wp_get_nav_menu_object()
• wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::_insert_post()
Show 11 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note Contributed by Codex

   Examples
   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')
   

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().