get_term_by

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

Если в поле $field не передано ни одно из значений: ‘slug’, ‘name’, ‘term_taxonomy_id’, то термин будет получаться по ID и управление полностью передается функции get_term(), которая работает быстрее чем get_term_by().

Еще одно отличие этой функции от get_term() – если термин получается не по ID, то результат будет получен на прямую из БД, а не из кэша, даже если он есть. А в get_term() объектный кэш работает всегда. Поэтому, если есть возможность пользуйтесь лучше get_term() или указывайте здесь в параметр $field ‘id’.

✈ 1 раз = 0.00072с = медленно | 50000 раз = 28.0с = медленно

Хуков нет.

Возвращает

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

get_term_by( $field, $value, $taxonomy, $output, $filter );
$field(строка) (обязательный)

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

  • slug – по альтернативному названию;
  • name – по названию;
  • term_taxonomy_id – по идентификатору таксономии термина;
  • 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 будет содержать подобный объект:

// получаем все рубрики текущего поста
$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

Код из


wp-includes/taxonomy.php

WP 4.7.2

<?php
function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
	global $wpdb;

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

	$tax_clause = $wpdb->prepare( "AND tt.taxonomy = %s", $taxonomy );

	if ( 'slug' == $field ) {
		$_field = 't.slug';
		$value = sanitize_title($value);
		if ( empty($value) )
			return false;
	} elseif ( 'name' == $field ) {
		// Assume already escaped
		$value = wp_unslash($value);
		$_field = 't.name';
	} elseif ( 'term_taxonomy_id' == $field ) {
		$value = (int) $value;
		$_field = 'tt.term_taxonomy_id';

		// No `taxonomy` clause when searching by 'term_taxonomy_id'.
		$tax_clause = '';
	} else {
		$term = get_term( (int) $value, $taxonomy, $output, $filter );
		if ( is_wp_error( $term ) || is_null( $term ) ) {
			$term = false;
		}
		return $term;
	}

	$term = $wpdb->get_row( $wpdb->prepare( "SELECT t.*, tt.* FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy AS tt ON t.term_id = tt.term_id WHERE $_field = %s", $value ) . " $tax_clause LIMIT 1" );
	if ( ! $term )
		return false;

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

	wp_cache_add( $term->term_id, $term, 'terms' );

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