term_exists()

💡 云策文档标注

概述

term_exists() 函数用于检查分类法术语是否存在，替代了已弃用的 is_term()。它接受术语 ID、slug 或名称作为参数，并返回不同的结果类型，具体取决于术语是否存在和是否指定了分类法。

关键要点

函数原名 is_term()，自 WordPress 2.3.0 引入。
参数：$term（必需，术语 ID、slug 或名称），$taxonomy（可选，分类法名称），$parent_term（可选，父术语 ID）。
返回值：术语不存在时返回 null；未指定分类法且术语 ID 存在时返回术语 ID；指定分类法且配对存在时返回包含 term_id 和 term_taxonomy_id 的数组；传入术语 ID 0 时返回 0。
内部使用 get_terms() 进行查询，并包含 apply_filters('term_exists_default_query_args', ...) Hook 以过滤默认查询参数。
返回的数组中的 ID 为字符串类型，如需整数需手动转换。

代码示例

$term = term_exists( 'Uncategorized', 'category' );
if ( $term !== 0 && $term !== null ) {
    echo __( "'Uncategorized' category exists!", "textdomain" );
}

注意事项

term_exists() 执行数据库查询，可能影响性能；get_term() 可作为替代，使用术语缓存。
检查术语存在时，注意处理返回值 null、0 或数组的情况。

📄 原文内容

Determines whether a taxonomy term exists.

Description

Formerly is_term() , introduced in 2.3.0.

For more information on this and similar theme functions, check out the Conditional Tags article in the Theme Developer Handbook.

Parameters

$termint|stringrequired: The term to check. Accepts term ID, slug, or name.
$taxonomystringoptional: The taxonomy name to use.
$parent_termintoptional: ID of parent term under which to confine the exists search.

Default:null

mixed Returns null if the term does not exist.
Returns the term ID if no taxonomy is specified and the term ID exists.
Returns an array of the term ID and the term taxonomy ID if the taxonomy is specified and the pairing exists.
Returns 0 if term ID 0 is passed to the function.

Source

function term_exists( $term, $taxonomy = '', $parent_term = null ) {
	global $_wp_suspend_cache_invalidation;

	if ( null === $term ) {
		return null;
	}

	$defaults = array(
		'get'                    => 'all',
		'fields'                 => 'ids',
		'number'                 => 1,
		'update_term_meta_cache' => false,
		'order'                  => 'ASC',
		'orderby'                => 'term_id',
		'suppress_filter'        => true,
	);

	// Ensure that while importing, queries are not cached.
	if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
		$defaults['cache_results'] = false;
	}

	if ( ! empty( $taxonomy ) ) {
		$defaults['taxonomy'] = $taxonomy;
		$defaults['fields']   = 'all';
	}

	/**
	 * Filters default query arguments for checking if a term exists.
	 *
	 * @since 6.0.0
	 *
	 * @param array      $defaults    An array of arguments passed to get_terms().
	 * @param int|string $term        The term to check. Accepts term ID, slug, or name.
	 * @param string     $taxonomy    The taxonomy name to use. An empty string indicates
	 *                                the search is against all taxonomies.
	 * @param int|null   $parent_term ID of parent term under which to confine the exists search.
	 *                                Null indicates the search is unconfined.
	 */
	$defaults = apply_filters( 'term_exists_default_query_args', $defaults, $term, $taxonomy, $parent_term );

	if ( ! empty( $taxonomy ) && is_numeric( $parent_term ) ) {
		$defaults['parent'] = (int) $parent_term;
	}

	if ( is_int( $term ) ) {
		if ( 0 === $term ) {
			return 0;
		}
		$args  = wp_parse_args( array( 'include' => array( $term ) ), $defaults );
		$terms = get_terms( $args );
	} else {
		$term = trim( wp_unslash( $term ) );
		if ( '' === $term ) {
			return null;
		}

		$args  = wp_parse_args( array( 'slug' => sanitize_title( $term ) ), $defaults );
		$terms = get_terms( $args );
		if ( empty( $terms ) || is_wp_error( $terms ) ) {
			$args  = wp_parse_args( array( 'name' => $term ), $defaults );
			$terms = get_terms( $args );
		}
	}

	if ( empty( $terms ) || is_wp_error( $terms ) ) {
		return null;
	}

	$_term = array_shift( $terms );

	if ( ! empty( $taxonomy ) ) {
		return array(
			'term_id'          => (string) $_term->term_id,
			'term_taxonomy_id' => (string) $_term->term_taxonomy_id,
		);
	}

	return (string) $_term;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘term_exists_default_query_args’, array $defaults, int|string $term, string $taxonomy, int|null $parent_term ): Filters default query arguments for checking if a term exists.

Uses	Description
sanitize_title()`wp-includes/formatting.php`	Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
get_terms()`wp-includes/taxonomy.php`	Retrieves the terms in a given taxonomy or list of taxonomies.
wp_unslash()`wp-includes/formatting.php`	Removes slashes from a string or recursively removes slashes from strings within an array.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Show 4 more Show less

Used by	Description
export_wp()`wp-admin/includes/export.php`	Generates the WXR export file for download.
category_exists()`wp-admin/includes/taxonomy.php`	Checks whether a category exists.
wp_insert_category()`wp-admin/includes/taxonomy.php`	Updates an existing Category or creates a new Category.
tag_exists()`wp-admin/includes/taxonomy.php`	Checks whether a post tag with a given name exists.
wp_create_term()`wp-admin/includes/taxonomy.php`	Adds a new term to the database if it does not already exist.
is_term()`wp-includes/deprecated.php`	Check if Term exists.
wp_unique_term_slug()`wp-includes/taxonomy.php`	Makes term slug unique, if it isn’t already.
wp_update_term()`wp-includes/taxonomy.php`	Updates term based on arguments provided.
wp_insert_term()`wp-includes/taxonomy.php`	Adds a new term to the database.
wp_set_object_terms()`wp-includes/taxonomy.php`	Creates term and taxonomy relationships.
wp_remove_object_terms()`wp-includes/taxonomy.php`	Removes term(s) associated with a given object.
wp_delete_term()`wp-includes/taxonomy.php`	Removes a term from the database.
register_taxonomy()`wp-includes/taxonomy.php`	Creates or modifies a taxonomy object.

Show 8 more Show less

Changelog

Version	Description
6.0.0	Converted to use `get_terms()`.
3.0.0	Introduced.

User Contributed Notes

Skip to note 4 content

Maje Media LLC

11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
The returned array of
```
['term_id' => ID, 'term_taxonomy_id' => ID]
```
returns a string for the ID instead of ints. If you need int values you’ll need to convert them to ints.
Log in to add feedback
Skip to note 5 content

Codex

11 years ago

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
Checks to see if ‘Uncategorized’ category exists
Check if the ‘Uncategorized’ category exists
Note: term_exists() runs a database query. get_term() can be used for the same purpose, except it uses the term cache.
```
$term = term_exists( 'Uncategorized', 'category' );
if ( $term !== 0 && $term !== null ) {
	echo __( "'Uncategorized' category exists!", "textdomain" );
}
```
Log in to add feedback
Skip to note 6 content

Codex

11 years ago

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
Checks to see if ‘Untagged’ post_tag category exists
Note: term_exists() runs a database query. get_term() can be used for the same purpose, except it uses the term cache.
```
$term = term_exists( 'Untagged', 'post_tag' );
if ( $term !== 0 && $term !== null ) {
	echo __( "'Untagged' post_tag exists!", "textdomain" );
}
```
Log in to add feedback

云策 WordPress 开发者社区

函数文档