get_term_by() WP 2.3.0

Получает указанный термин (элемент таксономии) по: имени (названию), ярлыку (слагу) или по ID термина.

Хуков нет.

Возвращает

Массив/WP_Term/false. Строку базы данных в указанном формате (массив/объект). Массив будет содержать следующие данные:

stdClass Object (
	[term_id]          => 9
	[name]             => Админка
	[slug]             => adminka-wordpress
	[term_group]       => 0
	[term_taxonomy_id] => 9
	[taxonomy]         => category
	[description]      => 
	[parent]           => 3
	[count]            => 3
	[filter]           => raw
)

Вернет false, если таксономии не существует или термин в ней не был найден.

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

get_term_by( $field, $value, $taxonomy, $output, $filter );

$field(строка) (обязательный)

Поле в БД, по которому будет производиться поиск параметра $value, может быть:

• slug - по альтернативному названию;
• name - по названию;
• term_taxonomy_id - по идентификатору таксономии термина;
• id - по идентификатору термина. C WP 5.5 можно ключ может быть и ID.

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

Значение которое нужно найти.

$taxonomy(строка) (обязательный)

Название таксономии, category, post_tag или название произвольной таксономии.

С версии 4.4. этот параметр является не обязательным, если в $field указано term_taxonomy_id.

$output(строка)

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

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

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

$filter(строка)

Тип фильтрации. Одно из значений:

• raw - просто вернет значение
• edit - фильтр esc_html() если это поле description, и фильтр esc_attr() если другое поле.
• db
• slug
• rss
• attribute - фильтр esc_attr()
• js - фильтр esc_js()

Смотрите параметр $context у функции sanitize_term_field(). Или загляните в код функции.
По умолчанию: 'raw'

Примеры

#1 Примеры как получить термины разных таксономий

// Получим рубрику "Новости" по её имени:
$term = get_term_by('name', 'Новости', 'category');

// Получим данные метки (таксономия post_tag) 
// альтернативное название (слаг) которой metka:
$term = get_term_by('slug', 'metka', 'post_tag');

// Получим термин "Новости" из таксономии "my_custom_taxonomy" по его имени:
$term = get_term_by('name', 'Новости', 'my_custom_taxonomy');

В результате этих примеров переменная $term будет содержать подобный объект:

stdClass Object
(
	[term_id] => 80
	[name] => Моя Рубрика
	[slug] => moya-rubrika
	[term_group] => 0
	[term_taxonomy_id] => 87
	[taxonomy] => my_tax
	[description] =>
	[parent] => 0
	[count] => 5
)

#2 Получение рубрики поста

Этот пример показывает, как получить все данные первой рубрики поста, с использованием get_term_by:

// получаем все рубрики текущего поста
$postCategories = get_the_category( $post->ID );

// собираем данные о всех рубриках поста в $myCategories
foreach ( $postCategories as $postCategory ) {
	$myCategories[] = get_term_by( 'id', $postCategory->cat_ID, 'category' );
}
// тут $myCategories содержит данные всех рубрик поста

// Первую рубрику поста можно получить так:
$myCategory = get_term_by('id', $postCategories[0]->cat_ID, 'category');

Это демонстрационный пример. По идее get_the_category() возвращает массив со всеми данными рубрики и, например, данные первые категории будут содержаться в первом элементе массива: $postCategories[0].

Заметки

• Важно: значение параметра $value не очищается, для поля 'name'в первом параметре $field, если нужно очистить это делается отдельно.

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

Заметки

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

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

Код get_term_by() get term by ^{WP 5.5.1}

<?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 );
}

Cвязанные функции

Из метки: term (термины таксономий)

Еще из раздела: Любые таксономии