WordPress как на ладони
rgbcode is looking for WordPress developers.

get_terms()WP 2.3.0

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

До версии WP 4.5 первый параметр get_terms() был названием таксономии или списком таких названий:

$terms = get_terms( 'post_tag', [
	'hide_empty' => false,
] );

С версии WP 4.5 название таксономии нужно указывать в элементе массива taxonomy в параметре $args, а не во втором параметре, как это было раньше:

$terms = get_terms( [
	'taxonomy' => 'post_tag',
	'hide_empty' => false,
] );

Обратная совместимость работает (функция понимает устарелый вызов).

C версии 4.6 эта функция является оберткой для класса WP_Term_Query{}. Таким образом стали поддерживаться запросы для метаданных (произвольных полей) - работает все точно также как meta_query в wp_query.

С помощью фильтров запрос можно как угодно изменить перед его отправкой, а также можно управлять выводом.

  • get_terms — фильтрует результат - найденные термины.
  • list_terms_exclusions — позволяет исключить термины. Получает список всех исключённых терминов.
  • get_terms_orderby — Фильтрует ORDER BY часть запроса.
Работает на основе: WP_Term_Query()
1 раз — 0.015166 сек (тормоз) | 50000 раз — 33.29 сек (очень медленно) | PHP 7.1.11, WP 4.9.5
Хуки из функции

Возвращает

WP_Term[]|int[]|Строку[]|Строку|WP_Error.

  • Массив объектов WP_Term — при успешном получении.
  • array() (пустой массив) — если термины не найдены.
  • WP_Error — если любая из указанных таксономий не существует.
  • Количество найденных терминов (в виде строки) — если fields = count.

Шаблон использования

$args = [
	'taxonomy'      => [ 'post_tag', 'my_tax' ], // название таксономии с WP 4.5
	'orderby'       => 'id',
	'order'         => 'ASC',
	'hide_empty'    => true,
	'object_ids'    => null,
	'include'       => array(),
	'exclude'       => array(),
	'exclude_tree'  => array(),
	'number'        => '',
	'fields'        => 'all',
	'count'         => false,
	'slug'          => '',
	'parent'         => '',
	'hierarchical'  => true,
	'child_of'      => 0,
	'get'           => '', // ставим all чтобы получить все термины
	'name__like'    => '',
	'pad_counts'    => false,
	'offset'        => '',
	'search'        => '',
	'cache_domain'  => 'core',
	'name'          => '',    // str/arr поле name для получения термина по нему. C 4.2.
	'childless'     => false, // true не получит (пропустит) термины у которых есть дочерние термины. C 4.2.
	'update_term_meta_cache' => true, // подгружать метаданные в кэш
	'meta_query'    => '',
];

$terms = get_terms( $args );

foreach( $terms as $term ){
	print_r( $term );
}

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

get_terms( $args, $deprecated );
$args(строка/массив)

Аргументы, в соответствии с которыми будет получен результат.

Среди них обязательным является аргумент $args['taxonomy'] в котором указывается название таксономии или несколько названий таксономий в массиве.
По умолчанию: массив аргументов по умолчанию

$deprecated(строка/массив)
До версии 4.5 в этом аргументе указывались параметры $args, а первом параметре $args указывались называния таксономий. С версии 4.5 названия таксономий указываются в аргументе $args['taxonomy'].
По умолчанию: массив аргументов по умолчанию

Аргументы параметра $args

Полный список параметров смотрите в методе WP_Term_Query::__construct()

taxonomy(строка/массив) (обязательный)
Название таксономии с которой работать. Можно указать несколько названий в виде массива. С версии WP 4.5, до этого названия таксономий указывались в первом параметре самой функции.
number(число)
Максимальное количество элементов, которые будут получены. Лимит.
По умолчанию: все.
object_ids(число/массив)

Укажите тут число или массив чисел, чтобы получить термины, у которых поле object_id таблицы wp_term_relationships совпадет с указанными значениями.

Обычно в поле object_id находятся ID записей к которым прикреплен термин.

include(строка/массив)
ID терминов, которые нужно включить в выборку. Если указать этот параметр, то многие другие станут бесполезными. Парсится через wp_parse_id_list().
По умолчанию: ''
exclude(строка/массив)
ID терминов, которые нужно исключить. Парсится через wp_parse_id_list().
По умолчанию: ''
exclude_tree(строка/массив)
ID родительских терминов, которые нужно исключить. Исключена будет вся ветка.
Парсится через wp_parse_id_list().
По умолчанию: ''
offset(число)
Верхний отступ в запросе. Сколько первых элементов пропустить. Указывать нужно число. По умолчанию без отступов.
orderby(строка)

Поле по которому сортировать результат. Может быть:

  • id или term_id - по ID.
  • name - по названию. По умолчанию.
  • count - по полю count в term_taxonomy - по количеству записей.
  • slug - по альтернативному названию.
  • description - по описанию.
  • term_group - по группе.
  • parent - по полю parent.

  • include - по порядку указанному в параметре $include
  • slug__in - с версии 4.9. В порядке указанном в параметре $slug.
  • meta_value - по значению произвольного поля
  • meta_value_num - по значению произвольного поля, значение будет интерпретироваться как число, а не строка.
  • ключ "meta_query" - в параметре $meta_query мы можем указать параметры запроса по метаполям, и там же указать ключ для конкретного запроса. Этот ключ можно использовать как ключ для сортировки по соответствующему метаполю.
  • none - не сортировать

Сортировкой управляет метод WP_Term_Query::parse_orderby()

Для произвольной сортировки такого типа можно использовать плагин YIKES Inc. Simple Taxonomy Ordering

По умолчанию: 'name'

order(строка)

Направление сортировки, указанной в параметре "orderby":

  • ASC - по порядку, от меньшего к большему (1, 2, 3; a, b, c);
  • DESC - в обратном порядке, от большего к меньшему (3, 2, 1; c, b, a).

По умолчанию: "ASC"

hide_empty(логический)
Скрывать ли термины в которых нет записей. 1(true) - скрывать пустые, 0(false) - показывать пустые.
По умолчанию: true
fields(строка)

Какие поля возвращать в результирующем массиве. Может быть:

  • all - Вернуть массив объектов (все данные) - по умолчанию;
  • ids - вернуть массив чисел;
  • names - вернуть массив строк.
  • count - (3.2+) возвращает количество найденных терминов.
  • id=>parent - вернуть массив, где ключ = ID термина, а значение = ID родительского термина.
  • id=>slug - вернуть массив, где ключ = ID термина, а значение = слаг (название для УРЛ) термина.
  • id=>name - вернуть массив, где ключ = ID термина, а значение = название (имя) термина.

По умолчанию: 'all'

count(логический)
true - вернет количество терминов. В этом случае, перебивает параметр fields.
false - вернет массив объектов терминов.
slug(строка/массив)
Укажите тут строку или массив строк, чтобы получить термины с указанными ярлыками (слагами).
По умолчанию: ''
hierarchical(логический)

Включать ли в результат термины, которые имеют не пустые дочерние термины (в которых есть записи). Т.е. в массив будут включены пустые термины, если у их дочерних терминах есть записи, даже если аргумент 'hide_empty' равен true.

  • true - да, включить;
  • false - нет, не включать.

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

Поиск по названиям термина и его ярлыку. Получит термины в названиях которых есть вхождение указанной тут строки. Т.е. запрос выглядит так: LIKE '%search_string%'.
По умолчанию: ''
name(строка/массив)
Укажите тут строку или массив строк, чтобы получить термины с указанными названиями.
По умолчанию: ''
name__like(строка)
Показать термины, в названии которых есть указанная строка. Поиск по строке.
По умолчанию: ''
description__like(строка)
Показать термины, в описании которых есть указанная строка. Поиск по строке. Например, если тут указать foo, то в запрос добавиться AND description LIKE '%foo%'.
По умолчанию: ''
pad_counts(логический)

Если передать true, то число которое показывает количество записей в родительских категориях будет суммой своих записей и записей из дочерних категорий. По умолчанию подсчитываются только свои записи.

pad_counts зависит от параметра parent потому что подсчет записей идет на уровне PHP и если например указать parent=0, то будут получены только верхние термины и pad_counts не сможет правильно посчитать кол-во записей в дочерних терминах. Чтобы обойти это ограничение, нужно получить все термины, не указывая parent, а потом в PHP удалить ненужные... Вот пример такого кода:

$terms = get_terms( array(
	'hide_empty'  => 0,
	'orderby'     => 'name',
	'order'       => 'ASC',
	'taxonomy'    => 'category',
	'pad_counts'  => 1
) );
// оставим только термины с parent=0
$terms = wp_list_filter( $terms, array('parent'=>0) );

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

get(строка)

Если указать 'all' то будут жёстко отключены параметры: childless, child_of, hide_empty, hierarchical и pad_counts. "Жёстко" - значит перебьет текущие установки для этих параметров. "Отключены" - значит им будет установлен параметр false или 0.

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

// фрагмент кода
if ( 'all' == $args['get'] ) {
	$args['childless'] = false;
	$args['child_of'] = 0;
	$args['hide_empty'] = 0;
	$args['hierarchical'] = false;
	$args['pad_counts'] = false;
}

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

child_of(число)

ID родительского термина. Вывести элементы таксономии, которые являются дочерними разделами указанного элемента. Будут получены все уровни вложенности, все дерево.

Если указаны несколько таксономий, параметр будет проигнорирован.
По умолчанию: 0

childless(true|false)

true пропустит (не получит) термины у которых есть дочерние термины.

Этот параметр не влияет на неиерархические таксономии.
По умолчанию: false

parent(число)

ID родительского термина, чтобы получить только прямых потомков.

Будет получен только первый уровень вложенности, а не все дерево как в параметре child_of. Если указать 0, то будут выведены термины верхнего уровня.
По умолчанию: ''

term_taxonomy_id(число/массив)
Укажите тут число или массив чисел, чтобы получить термины, у которых поле term_taxonomy_id совпадет с указанными значениями.
По умолчанию: ''
cache_domain(строка)
(3.2+) Позволяет установить уникальные ключ кэша, который будет использоваться в get_terms() при объектном кэшировании (object cache). Например, если вы используется один из фильтров get_terms(), чтобы изменить запрос (например 'terms_clausses'), установив 'cache_domain' в уникальное значение, позволить не перезаписывать сохраненный кэш для одинаковых запросов.
По умолчанию: 'core'
update_term_meta_cache(логический)
true — загрузить кэш метаданных, чтобы потом их можно было быстро получить. Кэш подгружается для полученных элементов.
По умолчанию: true
meta_query(массив)
Запрос для получения элементов на основе метаданных. Смотрите WP_Meta_Query.
meta_key(строка)
Получит термины у которых есть указанное метаполе. Можно использовать в связке с meta_value.
По умолчанию: ''
meta_value(строка)
Получит термины у которых значение метаполя равно указанному значению. Всегда используется в связке с meta_key.
По умолчанию: ''
suppress_filter(логический)
Подавлять работу фильтров или нет? Если выставить в true, то фильтр get_terms просто не будет работать для текущего запроса терминов.
По умолчанию: false (фильтры работают)
cache_results(true|false) (WP 6.4)

Нужно ли кэшировать результаты в Объектный кэш.

Такое кэширование для терминов было всегда. С WP 6.2 оно было перенесено в отдельную группу кэша term-queries, а в 6.4 был добавлен этот параметр, чтобы дать возможность отключить кэширование.

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

Примеры

5

#1 Выведем на экран список названий всех разделов таксономии "my_taxonomy":

$terms = get_terms( 'my_taxonomy' );

if( $terms && ! is_wp_error( $terms ) ){
	echo '<ul>';

	foreach( $terms as $term ){
		echo '<li>'. esc_html( $term->name ) .'</li>';
	}

	echo '</ul>';
}

В данном примере каждый $term из цикла foreach( $terms as $term ), будет содержать такую информацию:

[term_id]     => 162
[name]        => Здоровье
[slug]        => zdorove
[term_group]  => 0
[term_taxonomy_id] => 170
[taxonomy]    => my_taxonomy
[description] =>
[parent]      => 0
[count]       => 2
0

#2 Получим массив данных о всех категориях на сайте

Данные в массиве будут отсортированы по количеству записей (orderby=count) в каждой категории. Категории у которых нет записей все равно будут включены в массив (hide_empty=0).

$myterms = get_terms( 'taxonomy=category&orderby=count&hide_empty=0' );
0

#3 Вывод рубрик через разделитель

Пример, как вывести рубрики через разделитель: · ( &middot; ):

// получаем все термины из таксономии my_term
$terms = get_terms( [
	'taxonomy'   => 'my_term',
	'hide_empty' => false,
] );

// собираем их и выводим
if( $terms && ! is_wp_error( $terms ) ){

	$items = [];

	foreach( $terms as $term ){

		$items[] = sprintf( 
			'<a href="%s" title="%s">' . esc_html( $term->name ) . '</a>', 
			esc_url( get_term_link( $term ) ),
			esc_attr( sprintf( __( 'View all post filed under %s', 'my_localization_domain' ), $term->name ) )
		);

	}

	echo sprintf( '<p class="my-term-archive">%s</p>', implode( ' · ', $items ) );
}

В итоге получим подобный код:

<p class="my-term-archive">
	<a href="URL" title="название">название</a> ·
	<a href="URL" title="название">название</a>
</p>
0

#4 Вывод у текущего термина дочерних терминов в виде списка

Пусть у нас есть древовидная таксономия со следующей структурой:

- Рецепты
	- Холодные блюда
	- Горячие блюда
		- Каши
			- В мультиварке
			- В кастрюле
		- Котлеты

Общая задача: показывать только верхний уровень дочерних элементов.

Примеры:

  • Находясь в термине "Рецепты", показывать "Горячие блюда" и "Холодные блюда".
  • Находясь в термине "Холодные блюда", ничего не показывать.
  • Находясь в термине "Горячие блюда", показывать "Каши" и "Котлеты".
  • Находясь в термине "Каши", показывать "В мультиварке" и "В кастрюле".
  • Находясь в термине "В мультиварке", ничего не показывать.

Решение:

<?php

function first_child_terms_list() {

	$current_term = get_queried_object();

	// Если текущая страница не страница термина - прерываем выполнение функции
	if ( ! ( is_a( $current_term, 'WP_Term' ) ) ) {
		return;
	}

	// Если это термин не древовидной таксономии - прерываем выполнение функции
	if ( ! is_taxonomy_hierarchical( $current_term->taxonomy ) ) {
		return;
	}

	// Запрашиваем дочерние элементы верхнего уровня текущего термина
	$terms = get_terms( [
		'taxonomy'   => $current_term->taxonomy,
		'parent'     => $current_term->term_id,
		'hide_empty' => false,
	] );

	// Если возникла ошибка запроса или терминов нет - прерываем выполнение функции
	if ( is_wp_error( $terms ) || ! $terms ) {
		return;
	}

	?>

	<ul class="terms">
	<?php foreach ( $terms as $term ): ?>

		<li class="term">
			<?php
			printf(
				'<a href="%s" class="term-link">%s</a>',
				esc_url( get_term_link( $term ) ),
				esc_html( $term->name )
			)
			?>
		</li>

	<?php endforeach; ?>
	</ul>

	<?php
}

Выводим на странице термина:

first_child_terms_list();

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

С версии 2.3.0 Введена.
С версии 4.2.0 Introduced 'name' and 'childless' parameters.
С версии 4.4.0 Introduced the ability to pass 'term_id' as an alias of 'id' for the orderby parameter. Introduced the 'meta_query' and 'update_term_meta_cache' parameters. Converted to return a list of WP_Term objects.
С версии 4.5.0 Changed the function signature so that the $args array can be provided as the first parameter. Introduced 'meta_key' and 'meta_value' parameters. Introduced the ability to order results by metadata.
С версии 4.8.0 Introduced 'suppress_filter' parameter.

Код get_terms() WP 6.4.3

function get_terms( $args = array(), $deprecated = '' ) {
	$term_query = new WP_Term_Query();

	$defaults = array(
		'suppress_filter' => false,
	);

	/*
	 * Legacy argument format ($taxonomy, $args) takes precedence.
	 *
	 * We detect legacy argument format by checking if
	 * (a) a second non-empty parameter is passed, or
	 * (b) the first parameter shares no keys with the default array (ie, it's a list of taxonomies)
	 */
	$_args          = wp_parse_args( $args );
	$key_intersect  = array_intersect_key( $term_query->query_var_defaults, (array) $_args );
	$do_legacy_args = $deprecated || empty( $key_intersect );

	if ( $do_legacy_args ) {
		$taxonomies       = (array) $args;
		$args             = wp_parse_args( $deprecated, $defaults );
		$args['taxonomy'] = $taxonomies;
	} else {
		$args = wp_parse_args( $args, $defaults );
		if ( isset( $args['taxonomy'] ) && null !== $args['taxonomy'] ) {
			$args['taxonomy'] = (array) $args['taxonomy'];
		}
	}

	if ( ! empty( $args['taxonomy'] ) ) {
		foreach ( $args['taxonomy'] as $taxonomy ) {
			if ( ! taxonomy_exists( $taxonomy ) ) {
				return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
			}
		}
	}

	// Don't pass suppress_filter to WP_Term_Query.
	$suppress_filter = $args['suppress_filter'];
	unset( $args['suppress_filter'] );

	$terms = $term_query->query( $args );

	// Count queries are not filtered, for legacy reasons.
	if ( ! is_array( $terms ) ) {
		return $terms;
	}

	if ( $suppress_filter ) {
		return $terms;
	}

	/**
	 * Filters the found terms.
	 *
	 * @since 2.3.0
	 * @since 4.6.0 Added the `$term_query` parameter.
	 *
	 * @param array         $terms      Array of found terms.
	 * @param array|null    $taxonomies An array of taxonomies if known.
	 * @param array         $args       An array of get_terms() arguments.
	 * @param WP_Term_Query $term_query The WP_Term_Query object.
	 */
	return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );
}
73 комментария
Полезные 7Вопросы 2 Все
    Войти