get_terms()
Получает элементы (термины) указанной таксономии по указанным параметрам.
До версии 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[]|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
- по порядку указанному в параметре $includeslug__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 (фильтры работают)
Примеры
#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
#2 Получим массив данных о всех категориях на сайте
Данные в массиве будут отсортированы по количеству записей (orderby=count) в каждой категории. Категории у которых нет записей все равно будут включены в массив (hide_empty=0).
$myterms = get_terms( 'taxonomy=category&orderby=count&hide_empty=0' );
#3 Вывод рубрик через разделитель
Пример, как вывести рубрики через разделитель: ·
( · ):
// получаем все термины из таксономии 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>
#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. |