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' ) {

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

	if ( 'id' === $field || 'term_id' === $field ) {
		$term = get_term( (int) $value, $taxonomy, $output, $filter );
		if ( is_wp_error( $term ) || null === $term ) {
			$term = false;
		return $term;

	$args = array(
		'get'                    => 'all',
		'number'                 => 1,
		'taxonomy'               => $taxonomy,
		'update_term_meta_cache' => false,
		'orderby'                => 'none',

	switch ( $field ) {
		case 'slug' :
			$args['slug'] = $value;
		case 'name' :
			$args['name'] = $value;
		case 'term_taxonomy_id' :
			$args['term_taxonomy_id'] = $value;
			unset( $args[ 'taxonomy' ] );
		default :
			return false;

	$terms = get_terms( $args );
	if ( is_wp_error( $terms ) || empty( $terms ) ) {
		return false;

	$term = array_shift( $terms );

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

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