term_exists( int|string $term, string $taxonomy = , int $parent_term = null ): mixed

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.

Default:''

$parent_termintoptional
ID of parent term under which to confine the exists search.

Default:null

Return

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 ( 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;
		}

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

		$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;
}

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.

Changelog

VersionDescription
6.0.0Converted to use get_terms().
3.0.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    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" );
    }
  2. Skip to note 6 content

    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" );
    }

You must log in before being able to contribute a note or feedback.