get_terms() WP 2.3.0

Отримує елементи (терміни) таксономії за вказаними параметрами.

До версії 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()
1 раз – 0.015166 сек
(гальмо) | 50000 разів – 33.29 сек
(дуже повільно) |
PHP 7.1.11, WP 4.9.5

Хуки з функції
$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– По порядку вказаному в параметрі $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

Пошук за назвами терміна та його ярлику. Отримає терміни в назвах яких є входження вказаного рядка. Тобто. запит має такий вигляд:
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

#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

0

#2 Отримаємо масив даних про всі категорії на сайті

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

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

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>
*/

0

#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.0Introduced ‘suppress_filter’ parameter.

get terms WP 6.0.2

function get_terms( $args = array(), $deprecated = '' ) {
	$term_query = новий WP_Term_Query();

	$defaults = array(
		'suppress_filter' => false,
	);

	/*
	 * Legacy argument format ($taxonomy, $args) така precedence.
	 *
	 * We detect legacy argument format by checking if
	 * (a) a second non-empty parameter is passed, or
	 * (b) перший параметр shares no keys with 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 є не filtered, для 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 `$term_query` parameter.
	 *
	 * @param array $terms Array of found terms.
	 * @param array|null $taxonomies На array of taxonomies if known.
	 * @param array $args An array of get_terms() arguments.
	 * @param WP_Term_Query $term_query WP_Term_Query об'єкт.
	 */
	return apply_filters( 'get_terms', $terms, $term_query->query_vars['taxonomy'], $term_query->query_vars, $term_query );
}

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *