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,
]);
Зворотна сумісність працює (функція розуміє застарілий виклик).
З версії 4.6 ця функція є обгорткою для meta_query в wp_query .
За допомогою фільтрів запит можна як завгодно змінити перед його надсиланням, а також можна керувати виводом.
- get_terms – фільтрує результат – знайдені терміни.
- list_terms_exclusions – дозволяє виключити терміни. Отримує список усіх виключених термінів.
- get_terms_orderby — Фільтрує ORDER BY частину запиту.
WP_Term_Query()
wp_nav_menu_item_taxonomy_meta_box() ,
wp_count_terms() ,
wp_get_nav_menus() ,
wp_get_object_terms() ,
get_tags() ,
get_term_by (
) ,
(гальмо) | 50000 разів – 33.29 сек
(дуже повільно) |
PHP 7.1.11, WP 4.9.5
Хуки з функції
Використання
get_terms($args, $deprecated);
-
$args
(рядок/масив) - Аргументи, відповідно до яких буде отримано результат.
Серед них обов’язковим є аргумент $args[‘taxonomy’] , в якому вказується назва таксономії або кілька назв таксономій у масиві.
За промовчанням: масив аргументів за умовчанням -
$deprecated
(рядок/масив) -
До версії 4.5 у цьому аргументі вказувалися параметри $args, а в першому параметрі $args вказувалися назва таксономій. З версії 4.5 назви таксономій зазначаються у аргументі
$args[‘taxonomy’] .За промовчанням: масив аргументів за умовчанням
Аргументи параметра $args
Повний список параметрів дивіться у методі WP_Term_Query::__construct()
-
- Назва таксономії з якою працювати. Можна вказати кілька назв у вигляді масиву. З версії WP 4.5, до назви таксономій вказувалися в першому параметрі самої функції.
-
-
Максимальна кількість елементів, які будуть отримані. Ліміт.
За замовчуванням: все .
-
- Вкажіть число чи масив чисел, щоб отримати терміни, у яких поле
object_id
таблиці wp_term_relationships збігається із зазначеними значеннями.Зазвичай у полі object_id знаходяться ID записів, до яких прикріплений термін.
-
-
ID термінів, які потрібно включити у вибірку. Якщо вказати цей параметр, багато інших стануть марними. Париться через
wp_parse_id_list() .За замовчуванням: ”
-
-
ID термінів, які слід виключити. Париться через
wp_parse_id_list() .За замовчуванням: ”
-
-
ID батьківських термінів, які слід виключити. Виключена буде вся гілка.
Париться через
wp_parse_id_list() .За замовчуванням: ”
-
- Верхній відступ у запиті. Скільки перших елементів пропустити. Вказувати потрібно число. За промовчанням без відступів.
-
- Поле, за яким сортувати результат. Може бути:
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’
-
- Напрямок сортування, вказаного у параметрі “orderby”:
ASC
– По порядку, від меншого до більшого (1, 2, 3; a, b, c);DESC
– у зворотному порядку, від більшого до меншого (3, 2, 1; c, b, a).
Типово: “ASC”
-
-
Чи приховувати терміни, у яких немає записів. 1(true) – приховувати порожні, 0(false) – показувати порожні.
Типово: true
-
- Які поля повертати у результуючому масиві. Може бути:
all
– повернути масив об’єктів (всі дані) – за замовчуванням;ids
– Повернути масив чисел;names
– Повернути масив рядків.count
– (3.2+) повертає кількість знайдених термінів.id=>parent
– Повернути масив, де ключ = ID терміна, а значення = ID батьківського терміна.id=>slug
– Повернути масив, де ключ = ID терміна, а значення = слаг (назва для УРЛ) терміна.id=>name
– Повернути масив, де ключ = ID терміна, а значення = назва (ім’я) терміна.
За замовчуванням: ‘all’
-
-
true – поверне кількість термінів. У цьому випадку перебиває параметр
fields
.false – поверне масив об’єктів термінів.
-
-
Вкажіть рядок або масив рядків, щоб отримати терміни із зазначеними ярликами (складами).
За замовчуванням: ”
-
- Чи включати до результатів терміни, які мають не порожні дочірні терміни (у яких є записи). Тобто. до масиву будуть включені порожні терміни, якщо в їх дочірніх термінах є записи, навіть якщо аргумент ‘
hide_empty
‘ дорівнює true .true
– так, увімкнути;false
– Ні, не включати.
Типово: true
-
-
Пошук за назвами терміна та його ярлику. Отримає терміни в назвах яких є входження вказаного рядка. Тобто. запит має такий вигляд:
LIKE ‘%search_string%’ .За замовчуванням: ”
-
-
Вкажіть рядок або масив рядків, щоб отримати терміни із зазначеними назвами.
За замовчуванням: ”
-
-
Показати терміни, у назві яких є вказаний рядок. Пошук по рядку.
За замовчуванням: ”
-
-
Показати терміни, в описі яких є вказаний рядок. Пошук по рядку. Наприклад, якщо тут вказати
foo
, то запит додатися
AND description LIKE '%foo%'
.За замовчуванням: ”
-
- Якщо передати 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
-
- Якщо вказати ‘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; }
За замовчуванням: ”
-
- ID батьківського терміну. Вивести елементи таксономії, які є дочірніми розділами зазначеного елемента. Будуть отримані всі рівні вкладеності, дерево.
Якщо вказано кілька таксономій, параметр буде проігноровано.
За замовчуванням: 0 -
- true пропустить (не отримає) терміни, у яких є дочірні терміни.
Цей параметр не впливає на ієрархічні таксономії.
Типово: false -
- ID батьківського терміну отримати тільки прямих нащадків.
Буде отримано лише перший рівень вкладеності, а не все дерево, як у параметрі child_of . Якщо вказати 0, то буде виведено терміни верхнього рівня.
За замовчуванням: ” -
-
Вкажіть число чи масив чисел, щоб отримати терміни, у яких поле
term_taxonomy_id
збігається із зазначеними значеннями.За замовчуванням: ”
-
-
(3.2+) Дозволяє встановити унікальний ключ кешу, який буде використовуватися в get_terms() при об’єктному кешуванні (object cache). Наприклад, якщо ви використовуєте один із фільтрів get_terms(), щоб змінити запит (наприклад ‘terms_clausses’), встановивши ‘cache_domain’ в унікальне значення, дозволити не перезаписувати збережений кеш для однакових запитів.
За замовчуванням: ‘core’
-
-
true — завантажити кеш метаданих, щоб їх можна було швидко отримати. Кеш підвантажується для отриманих елементів.
Типово: true
-
-
Запит на отримання елементів на основі метаданих. Дивіться
WP_Meta_Query . -
-
Отримає терміни, у яких є вказане метаполі. Можна використовувати у зв’язку з
meta_value
.За замовчуванням: ”
-
-
Отримає терміни, у яких значення метаполя дорівнює вказаному значенню. Завжди використовується у зв’язці з
meta_key
.За замовчуванням: ”
-
-
Пригнічувати роботу фільтрів чи ні? Якщо виставити в 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>". $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('category', 'orderby=count&hide_empty=0');
#3 Виведення рубрик через роздільник
Приклад, як вивести рубрики через роздільник: ·
( · ):
// отримуємо всі терміни з таксономії 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 .= ' · ';
}
else {
$term_list .= '</p>';
}
}
echo $term_list;
}
/*
в результаті отримаємо такий код:
<p class="my_term-archive">
<a href="посилання" title="назва">назва</a> ·
<a href="посилання" 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 | Встановлено ‘name’ і ‘ childless ‘ parameters. |
З версії 4.4.0 | Встановлено здатність до pass ‘term_id’ як ‘ id’ for orderby parameter. Встановлено параметри ‘ meta_query ‘ and ‘update_term_meta_cache’ . Перевірено на відмітку з WP_Term об’єктів. |
З версії 4.5.0 | Змінена функція signature so that the $args array може бути здійснений as first parameter. Встановлено ‘ meta_key ‘ and ‘meta_value’ parameters. Introduced ability до order results by metadata. |
З версії 4.8.0 | Introduced ‘suppress_filter’ parameter. |