A WordPress-centric search engine for devs and theme authors

get_term_by ›

get_term_by ( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' )
Parameters: (5)
  • (string) $field Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
    Required: Yes
  • (string|int) $value Search for this term value
    Required: Yes
  • (string) $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
    Required: No
    Default: (empty)
  • (string) $output Constant OBJECT, ARRAY_A, or ARRAY_N
    Required: No
    Default: OBJECT
  • (string) $filter Optional, default is raw or no WordPress defined filter will applied.
    Required: No
    Default: 'raw'
  • (WP_Term|bool) WP_Term instance on success. Will return false if `$taxonomy` does not exist or `$term` was not found.
Defined at:
Change Log:
  • 4.4.0 ` $taxonomy` is optional if ` $field` is 'term_taxonomy_id'. Converted to return a WP_Term object if ` $output` is `OBJECT`.

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

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.


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

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

	$tax_clause = $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy );

	if ( 'slug' == $field ) {
		$_field = 't.slug';
		$value = sanitize_title($value);
		if ( empty($value) )
			return false;
	} elseif ( 'name' == $field ) {
		// Assume already escaped
		$value = wp_unslash($value);
		$_field = 't.name';
	} elseif ( 'term_taxonomy_id' == $field ) {
		$value = (int) $value;
		$_field = 'tt.term_taxonomy_id';

		// No `taxonomy` clause when searching by 'term_taxonomy_id'.
		$tax_clause = '';
	} else {
		$term = get_term( (int) $value, $taxonomy, $output, $filter );
		if ( is_wp_error( $term ) || is_null( $term ) ) {
			$term = false;
		return $term;

	$term = $wpdb->get_row( $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 $_field = %s", $value ) . " $tax_clause LIMIT 1" );
	if ( ! $term )
		return false;

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

	wp_cache_add( $term->term_id, $term, 'terms' );

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