get_terms()

  2.3.0     wp-includes / taxonomy.php  /  Кодекс WordPress

Функция, позволяющая получить (и вывести на сайте) элементы таксономий (рубрик, меток или кастомных таксономий) и информацию о них.

Если же надо получить текущий элемент таксономии, то воспользуйтесь функциями get_query_var() (co значением параметра равным term — так вы получите ярлык текущего элемента таксономии) и get_term_by() (со значением первого параметра равным slug).

ВозвращаетПри условии
Массив объектов элементов таксономий WP_Term.По умолчанию.
Массив из ID элементов таксономий.Параметр fields установлен в значение ids.
Массив из названий терминов.Параметр fields установлен в значение names.
Ассоциативный массив состоящих из ID элементов и ID их родителей.Параметр fields равен id=>parent.
Число элементов таксономий удовлетворяющих условиям.Параметр fields равен count.
Array() Пустой массив.Если терминов не найдено.
Объект класса WP_Error.Хотя бы одной из таксономий, переданных в параметре taxonomy не существует.
get_terms( $args = array(), $deprecated = '' )

Параметры

Раньше в первый параметр функции мы передавали название таксономии, а во второй – все параметры функции. Теперь же название таксономии передаётся также в массив $args параметром taxonomy.

$args
(строка|массив) параметры по типу, как в WP_Query, их тоже можно записать и в виде массива и в виде строки.

taxonomy
(строка|массив) название таксономии или массив таксономий, например array( 'category', 'post_tag' ).

number
(целое число) количество элементов, которые нужно вывести, по умолчанию выводятся все.

offset
(целое число) сколько элементов нужно пропустить, то есть если offset=2, то начинаем с третьего.

include
(целое число|строка|массив) укажите ID элементов, которые нужно вывести, можно указать число, числа через запятую в виде строки или одномерный массив чисел, например так:

$categories = get_terms( array( 'taxonomy' => 'category', 'include' => 1 ) );

или так:

$categories = get_terms( array( 'taxonomy' => 'category', 'include' => array( 1, 4 ) ) );

или даже так:

$args = array( 
	'taxonomy' => 'category', 
	'include' => array( 1, 4 ) 
);
 
$categories = get_terms( $args );

Если вы хотите исключить какие-то элементы, не пытайтесь использовать минус перед числом, просто смотрите следующий параметр.

exclude
(целое число|строка|массив) укажите ID элементов, которые нужно исключить.

exclude_tree
(целое число|строка|массив) если вы исключате родительские элементы и хотите сразу же исключить все дочерние, то этот параметр для вас.

orderby
(строка) сортировать по:

  • id — по ID элементов (по умолчанию),
  • parent — по ID родительских элементов,
  • count — по количеству постов,
  • name — по имени,
  • slug — по ярлыку,
  • term_group — по значениям колонки term_group в таблице wp_terms базы данных,
  • include — в том же порядке, в котором указаны элементы в параметре include,
  • meta_value и meta_value_num – по значению произвольного поля,
  • none — без сортировки;

order
(строка) порядок сортировки.

  • ASC — по возрастанию (по умолчанию),
  • DESC — по убыванию;

hide_empty
(логическое) нужно ли добавлять в результат также и пустые (без постов) рубрики/метки/элементы таксономий:

  • true — не нужно (по умолчанию),
  • false — нужно;

fields
(строка) в каком виде выводить результат:

  • all — массив объектов элементов таксономий (по умолчанию), после print_r() он будет выглядеть так:
$categories = get_terms( array( 'taxonomy' => 'category' ) );
print_r( $categories );
/*
Результат:
Array ( [0] => stdClass Object ( [term_id] => 1 [name] => Заметки [slug] => notes [term_group] => 0 [menu_order] => 0 [term_taxonomy_id] => 1 [taxonomy] => category [description] => [parent] => 0 [count] => 7 ) [1] => stdClass Object ( [term_id] => 4 [name] => Новости [slug] => news [term_group] => 0 [menu_order] => 0 [term_taxonomy_id] => 4 [taxonomy] => category [description] => [parent] => 0 [count] => 2 ) [2] => stdClass Object ( [term_id] => 11 [name] => Обновления [slug] => updates [term_group] => 0 [menu_order] => 0 [term_taxonomy_id] => 11 [taxonomy] => category [description] => [parent] => 4 [count] => 1 ) )
*/
  • ids — массив составленный из ID элементов, вот как он будет выглядеть, если пропустить его через функцию print_r()
$categories = get_terms( array( 'taxonomy' => 'category', 'fields' => 'ids' ) );
print_r( $categories );
/*
Результат:
Array ( [0] => 1 [1] => 4 [2] => 11 )
*/
  • names — возвращает массив наименований, например:
$categories = get_terms( array( 'taxonomy' => 'category', 'fields' => 'names' ) );
print_r( $categories );
/*
Результат:
Array ( [0] => Новости [1] => Заметки )
*/
  • count — (с версии 3.2) возвращает количество всех элементов таксономии, вне зависимости от других параметров. Для этих целей вы также можете использовать wp_count_terms().
$categories = get_terms( array( 'taxonomy' => 'category', 'fields' => 'count' ) );
echo $categories;
/*
Результат:
4
*/
  • id=>parent — ассоциативный массив состоящих из ID элементов и ID их родителей, если родительского элемента не существует, то возвращается 0, пример:
$categories = get_terms( array( 'taxonomy' => 'category', 'fields' => 'id=>parent' ) );
print_r( $categories );
/*
Результат:
Array ( [1] => 0 [4] => 0 [11] => 4 )
*/

slug
(строка) возвращает элементы, ярлыки которых совпадают с заданным значением.

hierarchical
(логическое) нужно ли включить в результат родительские элементы, даже если в них нет постов?

  • 1 — нужно (по умолчанию),
  • 0 — не нужно;

name__like
(строка) возвращает только те элементы, названия которых начинаются с заданного значения (без чувствительности в регистру), например:

// выведем через пробел все метки, начинающиеся с буквы "н"
$tags = get_terms( array( 'taxonomy' => 'post_tag', 'name__like' => 'н' ) );
foreach( $tags as $tag ){
	echo $tag->name . ' ';
}

pad_counts
(логическое) влияет только на числовые значения количества постов в родительских элементах.

  • 1 — количество постов родительского элемента суммируется с количеством постов дочерних элементов,
  • 0 — не суммируется (по умолчанию);

get
(строка)

  • all — вывести все элементы, вне зависимости от параметров offset, hide_empty, child_of (по умолчанию — пустая строка)

child_of
(целое число) вывести все элементы таксономии, которые являются дочерними для элемента с указанным ID вне зависимости от уровня вложенности.

parent
(целое число) вывести элементы таксономии, которые являются дочерними для элемента с указанным ID и находятся на первом уровне вложенности. Если указать 0, то будут выведены только элементы верхнего уровня.

meta_key
(строка) Укажите это значение ключа мета поля, если хотите получить только элементы таксономи, содержащие его.

meta_value
(строка) Значение мета поля элементов таксономии для указанного ключа meta_key.

meta_query
(массив) Работает так же, как и meta_query в WP_Query при выводе постов. О нём даже есть отдельный урок.

childless
(логическое) Принимает значения true/false. При установке в значени true, функция пропустит все термины, у которых есть дочерние элементы.

cache_domain
(строка) (с версии 3.2) если вы планируете использовать get_terms() с указанными параметрами несколько раз, укажите в качестве значения cache_domain уникальную фразу, чтобы задействовать кэш (по умолчанию — «core»).

WP_Term

Если параметр fields не изменен, то функция возвращает массив объектов WP_Term, каждый из которых содержит следующую информацию об элементе таксономии.

  • term_id – ID рубрики/метки/элемента таксономии
  • name – название
  • slug – ярлык
  • term_group – значение term_group из базы данных (особого применения пока что нет, в основном — в плагинах)
  • term_taxonomy_id – ID таксономии
  • taxonomy – название таксономии
  • description – описание элемента (можно заполнить в админке при создании и редактировании)
  • parent – ID родительского элемента
  • count – количество записей
  • order – номер по порядку при ручной сортировке

Или чекайте первый пример ниже.

Примеры

1. Выводим результат функции через print_r()

Прежде, чем мы перейдём к более практическим примерам, давайте посмотрим, что возвращает get_terms() при помощи PHP-функции print_r().

print_r( get_terms( array( 'taxonomy' => 'category' ) ) );
/*
Array
(
    [2] => WP_Term Object
        (
            [term_id] => 42
            [name] => Лайфстайл
            [slug] => lajfstajl
            [term_group] => 0
            [term_taxonomy_id] => 42
            [taxonomy] => category
            [description] => 
            [parent] => 0
            [count] => 1
            [filter] => raw
            [order] => 0
        )
 
    [4] => WP_Term Object
        (
            [term_id] => 1
            [name] => Трэвел
            [slug] => travel
            [term_group] => 0
            [term_taxonomy_id] => 1
            [taxonomy] => category
            [description] => 
            [parent] => 0
            [count] => 4
            [filter] => raw
            [order] => 4
        )
 
)
*/

2. Выводим отсортированные по имени рубрики в виде выпадающего списка

Приведу сразу же несложный пример с кучей комментов, иначе, как мне кажется, если я начну с документации функции, то некоторым будет непонятно, как её использовать.

// вытаскиваем все рубрики в массив $categories, описание параметров функции смотрите чуть ниже
$categories = get_terms( array( 'taxonomy' => 'category', 'orderby' => 'name', 'hide_empty' => 0 ) );
 
// если рубрики, соответствующие заданным параметрам, существуют
if( $categories ){
 
	// тогда создаем выпадающий список из них
	echo '<select>';
 
	// обращаемся к каждому объекту массива (в данном случае рубрика)
	foreach ( $categories as $cat ){
 
		// выводим элемент списка, где атрибут value равен ID рубрики, а $cat->name - название рубрики
		echo "<option value=\"{$cat->term_id}\">{$cat->name}</option>";
	}
	echo '</select>';
}

Вот что у меня получилось в результате выполнения этого кода на тестовом сайте:

список рубрик при помощи get_terms

Слева — сам список (открытый), а справа его HTML-код.

3. Выводим список из 5-и рубрик, отсортированных по количеству записей

В этом примере параметры функции задаются в виде массива:

$number = 5; // ради интереса вынесем переменную отдельно
$args = array(
	'taxonomy' => 'category',
	'number' => $number,
	'orderby' => 'count',
	'order' => 'DESC',
);
$terms = get_terms( $args );
if( $terms ){
	echo '<ul>';
	foreach( $terms as $term ) {
		echo '<li>' . $term->name . ' (' . $term->count . ')</li>';
	}
	echo '</ul>';
}
Кодекс WordPress: Таксономии: add_term_meta(), edit_term_link(), get_ancestors(), get_edit_term_link(), get_taxonomies(), get_taxonomy(), get_term(), get_term_by(), get_term_children(), get_term_field(), get_term_link(), get_term_meta(), get_term_parents_list(), get_terms(), get_the_term_list(), get_the_terms(), is_object_in_term(), is_tax(), is_taxonomy_hierarchical(), register_taxonomy(), register_taxonomy_for_object_type(), sanitize_term(), sanitize_term_field(), single_term_title(), taxonomy_exists(), term_description(), term_exists(), term_is_ancestor_of(), the_terms(), unregister_taxonomy(), unregister_taxonomy_for_object_type(), update_term_meta(), wp_count_terms(), wp_delete_term(), wp_get_object_terms(), wp_get_post_terms(), wp_get_term_taxonomy_parent_id(), wp_insert_term(), wp_set_object_terms(), wp_update_term()

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Комментарии — 34

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

Миша Рудрастых и WordPress

Полезности из мира WordPress и жизни студии.

Мой телеграм-канал