get_terms() │ WP 2.3.0

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

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

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

Возвращает

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

• taxonomy (строка/массив) (обязательный)
• number (число)
• object_ids (число/массив)
• include (строка/массив)
• exclude (строка/массив)
• exclude_tree (строка/массив)
• offset (число)
• orderby (строка)
• order (строка)
• hide_empty (логический)
• fields (строка)
• count (логический)
• slug (строка/массив)
• hierarchical (логический)
• search (строка)
• name (строка/массив)
• name__like (строка)
• description__like (строка)
• pad_counts (логический)
• get (строка)
• child_of (число)
• childless (true|false)
• parent (число)
• term_taxonomy_id (число/массив)
• cache_domain (строка)
• update_term_meta_cache (логический)
• meta_query (массив)
• meta_key (строка)
• meta_value (строка)
• suppress_filter (логический)
• cache_results (true|false) (WP 6.4)

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

search(строка)

Поиск по названиям термина и его ярлыку. Получит термины в названиях которых есть вхождение указанной тут строки. Т.е. запрос выглядит так: 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

Примеры

$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_id]     => 162
[name]        => Здоровье
[slug]        => zdorove
[term_group]  => 0
[term_taxonomy_id] => 170
[taxonomy]    => my_taxonomy
[description] =>
[parent]      => 0
[count]       => 2

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

// получаем все термины из таксономии 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>

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

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

Добавить свой пример