get_term() │ WP 2.3.0

Получает данные об элементе таксономии (термине) по переданному ID.

В функции есть два хука:

get_term - срабатывает всегда.
get_(taxonomy) - срабатывает для определенного элемента таксономии.

Оба хука в качестве параметров получают объект (массив) элемента и название таксономии. Оба хука должны вернуть объект (массив) элемента.

Второй хук term_(taxonomy) динамический, т.е. в нем (taxonomy) должно быть заменено на название таксономии. Например для категорий, название таксономии у которых "category", название фильтра будет таким: "get_category". Может пригодится для произвольных таксономий.

Функция кэширует результат и при повторном получении того же термина, запроса к БД уже не происходить - результат просто возвращается из кэша.

Чтобы получить термин по полю: name или slug, используйте get_term_by().

Функция идентична get_category(), только в этой функции можно указать название таксономии с которой работать.

Использует: sanitize_term(). Чистит элемент на основе правил фильтра указанного в параметре $filter.

Работает на основе: WP_Term()

Основа для: wp_get_nav_menu_object(), wp_get_term_taxonomy_parent_id(), get_the_category_by_ID(), get_ancestors(), get_term_by(), get_category(), get_cat_name()

1 раз — 0.000125 сек (быстро) | 50000 раз — 0.42 сек (очень быстро) | PHP 7.1.2, WP 4.7.3

Хуки из функции

Возвращает

WP_Term|Массив|WP_Error|null.

WP_Term (объект термина) — когда термин найден и $output = OBJECT (по умолчанию).
Массив — когда термин найден и $output = ARRAY_A или $output = ARRAY_N.
null — когда термин не найден.
WP_Error (объект) — когда таксономии не существует.

Использование

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

$term(число/объект) (обязательный)

Если передан ID, то данные будут получены из БД. Если передан объект, то будут применены фильтры и возвращен переданный объект.

$taxonomy(строка)

Название таксономии, к которой принадлежит элемент $term.
С версии 4.4. параметр стал необязательным.
По умолчанию: ''

$output(строка)

Каким видом массива возвращать данные:

OBJECT - объект.
ARRAY_A - ассоциативный массив.
ARRAY_N - индексированный массив.

По умолчанию: OBJECT

$filter(строка)

Как очищать поля массива перед возвращением.
По умолчанию: 'raw'

Примеры

#1 Получим данные об элементе таксономии из БД:

$term_id = 65;
$taxonomy = 'my_taxonomy'; // С версии 4.4. параметр стал не обязательным.
$term = get_term( $term_id, $taxonomy );
// Теперь, переменная содержит данные о элементе таксономии.

// Альтернативное название элемента находится здесь
$slug = $term->slug;

// Название элемента
$name = $term->name;

// А так мы получим описание элемента таксономии
$desc = $term->description;

#2 Получение элемента таксономии без указания таксономии

С версии 4.4. стало возможными не указывать параметр $taxonomy:

$term = get_term( 562 );
print_r( $term );

/* Выведет:
WP_Term Object
(
	[term_id] => 562
	[name] => Записи
	[slug] => zapisi
	[term_group] => 0
	[term_taxonomy_id] => 582
	[taxonomy] => my_taxonomy_name
	[description] =>
	[parent] => 0
	[count] => 1
	[filter] => raw
)
*/

Заметки

Смотрите: sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.

Список изменений

С версии 2.3.0	Введена.
С версии 4.4.0	Converted to return a WP_Term object if `$output` is `OBJECT`. The `$taxonomy` parameter was made optional.

Код `get_term() get term` ^{WP 6.6.2}

wp-includes/taxonomy.php

function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
	if ( empty( $term ) ) {
		return new WP_Error( 'invalid_term', __( 'Empty Term.' ) );
	}

	if ( $taxonomy && ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
	}

	if ( $term instanceof WP_Term ) {
		$_term = $term;
	} elseif ( is_object( $term ) ) {
		if ( empty( $term->filter ) || 'raw' === $term->filter ) {
			$_term = sanitize_term( $term, $taxonomy, 'raw' );
			$_term = new WP_Term( $_term );
		} else {
			$_term = WP_Term::get_instance( $term->term_id );
		}
	} else {
		$_term = WP_Term::get_instance( $term, $taxonomy );
	}

	if ( is_wp_error( $_term ) ) {
		return $_term;
	} elseif ( ! $_term ) {
		return null;
	}

	// Ensure for filters that this is not empty.
	$taxonomy = $_term->taxonomy;

	$old_term = $_term;
	/**
	 * Filters a taxonomy term object.
	 *
	 * The {@see 'get_$taxonomy'} hook is also available for targeting a specific
	 * taxonomy.
	 *
	 * @since 2.3.0
	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
	 *
	 * @param WP_Term $_term    Term object.
	 * @param string  $taxonomy The taxonomy slug.
	 */
	$_term = apply_filters( 'get_term', $_term, $taxonomy );

	/**
	 * Filters a taxonomy term object.
	 *
	 * The dynamic portion of the hook name, `$taxonomy`, refers
	 * to the slug of the term's taxonomy.
	 *
	 * Possible hook names include:
	 *
	 *  - `get_category`
	 *  - `get_post_tag`
	 *
	 * @since 2.3.0
	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
	 *
	 * @param WP_Term $_term    Term object.
	 * @param string  $taxonomy The taxonomy slug.
	 */
	$_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );

	// Bail if a filter callback has changed the type of the `$_term` object.
	if ( ! ( $_term instanceof WP_Term ) ) {
		return $_term;
	}

	// Sanitize term, according to the specified filter.
	if ( $_term !== $old_term || $_term->filter !== $filter ) {
		$_term->filter( $filter );
	}

	if ( ARRAY_A === $output ) {
		return $_term->to_array();
	} elseif ( ARRAY_N === $output ) {
		return array_values( $_term->to_array() );
	}

	return $_term;
}