WordPress как на ладони
rgbcode is looking for WordPress developers.
Kama и campusboy2.4 года назад12 EN

get_term_by() │ WP 2.3.0

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

Важно: $value не очищается, когда $field=name, вам нужно делать это самостоятельно.

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

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

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

Хуков нет.

Возвращает

WP_Term|Массив|false.

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

    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
)

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

  • 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'

Примеры

0

#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' );

// Получение термина по id (term_id) из таксономии `category`.
get_term_by( 'id', 12, 'category' )

Для получения термина по ID лучше использовать функцию get_term().

В результате этих примеров переменная $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
)
0

#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].

Заметки

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

С версии 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 6.6.2

wp-includes/taxonomy.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 );
}

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

Любые таксономии

12 комментариев
Полезные 3 Все
    Войти