WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

get_term_by() WP 2.3.0

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

Значение не очищается для поля name, вам нужно делать это самостоятельно.

Функция всегда возвращает первый термин, который подходит под условия параметров: $field-$value-$taxonomy. Однако, когда $field=name, то может быть несколько терминов с одинаковыми названиями, в таком случае функция вернет только первый найденный термин, если нужны все найденные, то используйте функцию get_terms().

Работает на основе: get_terms(), get_term()
1 раз = 0.001272с = очень медленно | 50000 раз = 4.95с = быстро | PHP 7.1.11, WP 4.9.6

Хуков нет.

Возвращает

Массив/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, если таксономии не существует или термин в ней не был найден.

Предупреждение: все поля массива возвращаются как строки, term_id в том числе. Поэтому перед дальнейшем использованием преобразуйте числовые значения в числа, где это необходимо.

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

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.

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

С версии 2.3.0 Введена.
С версии 4.4.0 $taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT.
С версии 5.5.0 Added 'ID' as an alias of 'id' for the $field parameter.

Код get_term_by() WP 5.5.1

wp-includes/taxonomy.php
<?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 (термины таксономий)

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

12 комментов
Полезные 3 Все