term_exists() WordPress Function

The term_exists() function is a useful tool for checking whether a given term already exists in the WordPress database. This can be helpful when you want to avoid creating duplicate terms, or when you need to know if a given term exists before attempting to perform some operation on it.

term_exists( int|string $term, string $taxonomy = '', int $parent = null ) #

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.


Top ↑

Parameters

$term

(int|string)(Required)The term to check. Accepts term ID, slug, or name.

$taxonomy

(string)(Optional) The taxonomy name to use.

Default value: ''

$parent

(int)(Optional) ID of parent term under which to confine the exists search.

Default value: null


Top ↑

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.


Top ↑

Source

File: wp-includes/taxonomy.php

function term_exists( $term, $taxonomy = '', $parent = 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 ) ) {
		// @todo Disable caching once #52710 is merged.
		$defaults['cache_domain'] = microtime();
	}

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

	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 ) ) {
			$defaults['parent'] = (int) $parent;
		}

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


Top ↑

Changelog

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

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More
Show More