WordPress как на ладони
wordpress jino

get_terms() WP 2.3.0

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

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

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

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

$args = array(
	'taxonomy' => 'post_tag',
	'hide_empty' => false,
);
$terms = get_terms( $args );

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

C версии 4.6. появился класс мета запросов WP_Term_Query{}. И теперь функция get_terms() является оберткой для этого класса.

Работает на основе: WP_Term_Query()
✈ 1 раз = 0.0051с = очень медленно | 50000 раз = 2.3с = быстро
Хуки из функции:
Возвращает
  • Массив объектов WP_Term, содержащих в данные об элементах таксономии.
  • Если термины не найдены, то вернет пустой массив - array().
  • Вернет объект WP_Error, если любой из указанных таксономий не существует.
  • Если аргумент fields = count, то вернет количество найденных терминов в виде строки.

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

get_terms( $args, $deprecated );

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

$args = array(
	'taxonomy'      => array( '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'    => '',
); 

$myterms = get_terms( $args );

foreach( $myterms as $term ){
	print_r($term);
}
$args(строка/массив)

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

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

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

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

Все параметры из ядра WordPress смотрите в методе WP_Term_Query::__construct

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

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

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

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

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

  • id или term_id - по ID - По умолчанию
  • count - по количеству записей
  • name - по названию
  • slug - по альтернативному названию
  • description - по описанию
  • term_group - по группе
  • include - по порядку указанному в параметре $include
  • meta_value - по значению произвольного поля
  • meta_value_num - по значению произвольного поля, значение будет интерпретироваться как число, а не строка.
  • ключ "meta_query" - в параметре $meta_query мы можем указать параметры запроса по метаполям, и там же указать ключ для конкретного запроса. Этот ключ можно использовать как ключ для сортировки по соответствующему метаполю.
  • none - не сортировать

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

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

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 - вернет массив объектов терминов.
name(строка/массив)
Укажите тут строку или массив строк, чтобы получить термины с указанными названиями.
По умолчанию: ''
slug(строка/массив)
Укажите тут строку или массив строк, чтобы получить термины с указанными ярлыками (слагами).
По умолчанию: ''
hierarchical(логический)

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

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

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

search(строка)
Поиск по названиям термина и его ярлыку. Получит термины в названиях которых есть вхождение указанной тут строки. Т.е. запрос выглядит так: LIKE '%search_string%'.
По умолчанию: ''
name__like(строка)
Показать термины, в названии которых есть указанная строка. Поиск по строке.
По умолчанию: ''
description__like (строка)
Показать термины, в описании которых есть указанная строка. Поиск по строке.
По умолчанию: ''
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

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 (фильтры работают)

Примеры

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

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

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

#1.2 Получим все разделы ссылок:

$mylinks_categories = get_terms('link_category', 'orderby=count&hide_empty=0');

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

$terms = get_terms( 'my_taxonomy' );

if( $terms && ! is_wp_error($terms) ){
	echo "<ul>";
	foreach( $terms as $term ){
		echo "<li>". $term->name ."</li>";

	}
	echo "</ul>";
}

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

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

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

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

// получаем все термины из таксономии my_term
$args = array( 'hide_empty=0' );
$terms = get_terms('my_term', $args);

// собираем их и выводим
if ( !empty( $terms ) && !is_wp_error( $terms ) ) {
	$count = count($terms);
	$i=0;
	$term_list = '<p class="my_term-archive">';
	foreach ($terms as $term) {
		$i++;
		$term_list .= '<a href="' . get_term_link( $term ) . '" title="' . sprintf(__('View all post filed under %s', 'my_localization_domain'), $term->name) . '">' . $term->name . '</a>';
		if ($count != $i) {
			$term_list .= ' &middot; ';
		}
		else {
			$term_list .= '</p>';
		}
	}
	echo $term_list;
}

/*
 в итоге получим подобный код:
 <p class="my_term-archive">
	<a href="ссылка" title="название">название</a> · 
	<a href="ссылка" title="название">название</a>
 </p>
*/

Заметки

  1. Использует фильтр 'get_terms', когда нужный термин найден в кэше. Фильтр срабатывает для каждого термина, до того как он попадет в итоговый массив.

  2. Использует фильтр 'list_terms_exclusions', который фильтрует итоговый результат, учитывая аргументы параметра $args.

Код get terms: wp-includes/taxonomy.php WP 4.9

<?php
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         $taxonomies An array of taxonomies.
	 * @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 );
}

Cвязанные функции

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

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

get_terms 56 комментариев
Полезные 4 Вопросы 3 Все
  • Сергей

    Вот у вас есть пример как сделать вывод Вывод #3 Вывод рубрик через разделитель.
    Но как сделать так что бы можно было еще присвоить class "current или active" ну вы поняли что это значит.
    В wp_list_categories это есть но нужно без этой функции, а циклом помогите пж не могу нигде найти. secret

    3
    Ответить3 месяца назад #
  • Roman

    Есть ли какое нибудь решения для выборки таксономии, которая пересекается с другой таксономией в записях.
    Пример
    есть таксономия size
    и таксономия type
    и записи product
    Вывести текущие размеры(size) товаров(product) типа обувь(type->term_id = 2).
    Буду очень благодарен за ответ)

    Ответить9 дней назад #

Здравствуйте, !

Ваш комментарий