WP_Term::get_instance() │ public static │ WP 4.4.0

Retrieve WP_Term instance.

Method of the class: WP_Term{}

No Hooks.

Return

WP_Term|WP_Error|false. Term object, if found. WP_Error if $term_id is shared between taxonomies and there's insufficient data to distinguish which term is intended. False for other failures.

Usage

$result = WP_Term::get_instance( $term_id, $taxonomy );

$term_id(int) (required)

Term ID.

$taxonomy(string)

Limit matched terms to those matching $taxonomy. Only used for disambiguating potentially shared terms.
Default: null

Notes

• Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

WP_Term::get_instance() WP Term::get instance code ^{WP 6.5.2}

public static function get_instance( $term_id, $taxonomy = null ) {
	global $wpdb;

	$term_id = (int) $term_id;
	if ( ! $term_id ) {
		return false;
	}

	$_term = wp_cache_get( $term_id, 'terms' );

	// If there isn't a cached version, hit the database.
	if ( ! $_term || ( $taxonomy && $taxonomy !== $_term->taxonomy ) ) {
		// Any term found in the cache is not a match, so don't use it.
		$_term = false;

		// Grab all matching terms, in case any are shared between taxonomies.
		$terms = $wpdb->get_results( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE t.term_id = %d", $term_id ) );
		if ( ! $terms ) {
			return false;
		}

		// If a taxonomy was specified, find a match.
		if ( $taxonomy ) {
			foreach ( $terms as $match ) {
				if ( $taxonomy === $match->taxonomy ) {
					$_term = $match;
					break;
				}
			}

			// If only one match was found, it's the one we want.
		} elseif ( 1 === count( $terms ) ) {
			$_term = reset( $terms );

			// Otherwise, the term must be shared between taxonomies.
		} else {
			// If the term is shared only with invalid taxonomies, return the one valid term.
			foreach ( $terms as $t ) {
				if ( ! taxonomy_exists( $t->taxonomy ) ) {
					continue;
				}

				// Only hit if we've already identified a term in a valid taxonomy.
				if ( $_term ) {
					return new WP_Error( 'ambiguous_term_id', __( 'Term ID is shared between multiple taxonomies' ), $term_id );
				}

				$_term = $t;
			}
		}

		if ( ! $_term ) {
			return false;
		}

		// Don't return terms from invalid taxonomies.
		if ( ! taxonomy_exists( $_term->taxonomy ) ) {
			return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
		}

		$_term = sanitize_term( $_term, $_term->taxonomy, 'raw' );

		// Don't cache terms that are shared between taxonomies.
		if ( 1 === count( $terms ) ) {
			wp_cache_add( $term_id, $_term, 'terms' );
		}
	}

	$term_obj = new WP_Term( $_term );
	$term_obj->filter( $term_obj->filter );

	return $term_obj;
}