# get_term_by()

URL: https://chugunov.pro/api-wordpress/functions/get_term_by/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.3.0.

## Сигнатура

```php
get_term_by( string $field, string|int $value, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' ): WP_Term|array|false
```

## Описание

Предупреждение: $value не экранируется для $field «name». При необходимости вы должны сделать это сами.
Поле $field по умолчанию равно «id», поэтому для field можно также использовать null, но это не рекомендуется.
Если $value не существует, возвращаемым значением будет false. Если $taxonomy существует и существуют сочетания $field и $value, термин будет возвращён.
Эта функция всегда возвращает первый термин, соответствующий сочетанию $field– $value–$taxonomy, указанному в параметрах. Если ваш запрос, вероятно, совпадёт более чем с одним термином (что вероятно, например, когда $field равно «name»), используйте вместо этого get_terms(); так вы получите все совпадающие термины и сможете задать собственную логику выбора нужного.
См. alsosanitize_term_field(): параметр $context перечисляет доступные значения для параметра get_term_by() $filter.

## Параметры

- `$field` `string` — обязательный. Либо 'slug', 'name', 'term_id' (или 'id', 'ID'), либо 'term_taxonomy_id'.
- `$value` `string|int` — обязательный. Искать по этому значению термина.
- `$taxonomy` `string` — необязательный, по умолчанию `''`. Имя таксономии. Необязательно, если $field равно 'term_taxonomy_id'.
- `$output` `string` — необязательный, по умолчанию `OBJECT`. Требуемый тип возврата. Один из OBJECT, ARRAY_A или ARRAY_N, что соответствует объекту WP_Term, ассоциативному массиву или числовому массиву соответственно.
- `$filter` `string` — необязательный, по умолчанию `'raw'`. Как очищать поля термина. Значение по умолчанию 'raw'.

## Возвращаемое значение

`WP_Term|array|false` — WP_Term $output $taxonomy $term

## Исходный код

Файл: `wp-includes/taxonomy.php:1099`

```php
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;
	}

	// No need to perform a query for empty 'slug' or 'name'.
	if ( 'slug' === $field || 'name' === $field ) {
		$value = (string) $value;

		if ( 0 === strlen( $value ) ) {
			return false;
		}
	}

	if ( 'id' === $field || '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',
		'suppress_filter'        => true,
	);

	switch ( $field ) {
		case 'slug':
			$args['slug'] = $value;
			break;
		case 'name':
			$args['name'] = $value;
			break;
		case 'term_taxonomy_id':
			$args['term_taxonomy_id'] = $value;
			unset( $args['taxonomy'] );
			break;
		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 );
}
```

## История изменений

- 5.5.0 — Added 'ID' as an alias of 'id' for the $field parameter.
- 4.4.0 — $taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT.
- 2.3.0 — Introduced.

## Связанные

Использует: [`get_terms`](https://chugunov.pro/api-wordpress/functions/get_terms/), [`taxonomy_exists`](https://chugunov.pro/api-wordpress/functions/taxonomy_exists/), [`get_term`](https://chugunov.pro/api-wordpress/functions/get_term/), [`is_wp_error`](https://chugunov.pro/api-wordpress/functions/is_wp_error/).
Используется в: `WP_REST_Menus_Controller::create_item`, [`get_linksbyname`](https://chugunov.pro/api-wordpress/functions/get_linksbyname/), [`get_linkobjectsbyname`](https://chugunov.pro/api-wordpress/functions/get_linkobjectsbyname/), `WP_Query::get_queried_object`, `WP_Query::get_posts`, [`get_category_by_slug`](https://chugunov.pro/api-wordpress/functions/get_category_by_slug/), [`get_cat_ID`](https://chugunov.pro/api-wordpress/functions/get_cat_id/), [`get_term_link`](https://chugunov.pro/api-wordpress/functions/get_term_link/), [`wp_unique_term_slug`](https://chugunov.pro/api-wordpress/functions/wp_unique_term_slug/), [`wp_update_term`](https://chugunov.pro/api-wordpress/functions/wp_update_term/), [`wp_insert_term`](https://chugunov.pro/api-wordpress/functions/wp_insert_term/), [`_wp_preview_terms_filter`](https://chugunov.pro/api-wordpress/functions/_wp_preview_terms_filter/), [`get_bookmarks`](https://chugunov.pro/api-wordpress/functions/get_bookmarks/), [`get_post_format_link`](https://chugunov.pro/api-wordpress/functions/get_post_format_link/), [`wp_update_nav_menu_object`](https://chugunov.pro/api-wordpress/functions/wp_update_nav_menu_object/), [`wp_get_nav_menu_object`](https://chugunov.pro/api-wordpress/functions/wp_get_nav_menu_object/), `wp_xmlrpc_server::_insert_post`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/get_term_by/