WordPress как на ладони
rgbcode is looking for WordPress developers. Очень Удобный и Быстрый Хостинг для сайтов на WordPress. Пользуюсь сам и вам рекомендую!

get_categories()WP 2.1.0

Получает категории в виде массива объектов.

По каким критериям получить категории и как их отсортировать указывается в параметрах функции.

Параметры, передаваемые этой функции, очень похожи на параметры wp_list_categories(). Они также могут быть переданы в виде массива или строки запроса: type=post&order=DESC.

Работает на основе: get_terms()
Основа для: wp_list_categories()
1 раз — 0.005625 сек (очень медленно) | 50000 раз — 11.98 сек (медленно) | PHP 7.1.11, WP 4.9.5
Хуки из функции

Возвращает

Массив.

  • Массив объектов WP_Term (категорий).
  • Пустой массив, если не удалось получить категории.
Array (
	[0] => WP_Term Object (
			[term_id] => 7
			[name] => Codex
			[slug] => codex
			[term_group] => 0
			[term_taxonomy_id] => 7
			[taxonomy] => category
			[description] =>
			[parent] => 3
			[count] => 17
			[filter] => raw
			[term_order] => 1
			[cat_ID] => 7
			[category_count] => 17
			[category_description] =>
			[cat_name] => Codex
			[category_nicename] => codex
			[category_parent] => 3
		)

	[1] => WP_Term Object ( ... )
	...
)

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

$categories = get_categories( [
	'taxonomy'     => 'category',
	'type'         => 'post',
	'child_of'     => 0,
	'parent'       => '',
	'orderby'      => 'name',
	'order'        => 'ASC',
	'hide_empty'   => 1,
	'hierarchical' => 1,
	'exclude'      => '',
	'include'      => '',
	'number'       => 0,
	'pad_counts'   => false,
	// полный список параметров смотрите в описании функции http://wp-kama.ru/function/get_terms
] );

if( $categories ){
	foreach( $categories as $cat ){
		// Данные в объекте $cat

		// $cat->term_id
		// $cat->name (Рубрика 1)
		// $cat->slug (rubrika-1)
		// $cat->term_group (0)
		// $cat->term_taxonomy_id (4)
		// $cat->taxonomy (category)
		// $cat->description (Текст описания)
		// $cat->parent (0)
		// $cat->count (14)
		// $cat->object_id (2743)
		// $cat->cat_ID (4)
		// $cat->category_count (14)
		// $cat->category_description (Текст описания)
		// $cat->cat_name (Рубрика 1)
		// $cat->category_nicename (rubrika-1)
		// $cat->category_parent (0)

	}
}

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

get_categories( $args );
$args(массив|строка)

Параметры для получения категорий. Полный список параметров смотрите в get_terms().

По умолчанию: '' - предустановки

Аргументы $args

Полный список параметров смотрите в get_terms().

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

Нужно ли кэшировать результаты в Объектный кэш.

Такое кэширование для терминов было всегда. С WP 6.2 оно было перенесено в отдельную группу кэша term-queries, а в 6.4 был добавлен этот параметр, чтобы дать возможность отключить кэширование.

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

Примеры

3

#1 Список категорий и их описание

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

<?php
$categories = get_categories( [
	'orderby' => 'name',
	'order' => 'ASC'
] );

foreach( $categories as $category ){
	echo '<p>Category: <a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . '>' . $category->name.'</a> </p> ';
	echo '<p> Description:'. $category->description . '</p>';
	echo '<p> Post Count: '. (int) $category->count . '</p>';
}
?>
0

#2 Получение только категорий верхнего уровня

Для этого, установите значение 'parent' => 0. Этот пример получает ссылку и название категорий верхнего уровня.

$cats = get_categories( array(
	'orderby' => 'name',
	'parent'  => 0
) );

foreach ( $cats as $cat ) {

	printf( '<a href="%1$s">%2$s</a><br />',
		esc_url( get_category_link( $cat->term_id ) ),
		esc_html( $cat->name )
	);
}
0

#3 Выпадающий список

Для того, чтобы создать выпадающий список из категорий мы можем воспользоваться другой специальной для этой цели, функцией wp_dropdown_categories():

wp_dropdown_categories( [
	'hide_empty' => 0,
	'name' => 'category_parent',
	'orderby' => 'name',
	'selected' => $category->parent,
	'hierarchical' => true,
	'show_option_none' => __('None')
] );

Однако с таким подходом мы лишимся определенной гибкости в настройке списка, так как мы получи уже полностью сформированный список.

Поэтому, в некоторых случаях будет логичнее создать выпадающий список с помощью этой функции - get_categories(). Пример (предполагается что нам нужно вывести подкатегории (дочерние) категории 10):

<select name="event-dropdown" onchange="document.location.href = this.options[ this.selectedIndex ].value;">

	<option value=""><?php echo esc_attr( 'Выберите событие' ); ?></option>

	<?php
	$categories = get_categories( 'child_of=10' );

	foreach( $categories as $category ){

		$option = '<option value="' . get_term_link( $category ) . '">';
		$option .= $category->name;
		$option .= ' (' . $category->count . ')';
		$option .= '</option>';

		echo $option;
	}
	?>

</select>
-3

#4 Получим только категории в которых есть посты

По умолчанию функция get_category() возвращает ТОЛЬКО категории, в которых есть посты (не пустые категории). Это означает, что если для категории не назначен пост, то такая категория не будет получена.

Чтобы этого избежать и показать все категории независимо есть в ней посты или нет, нужно указать параметр 'hide_empty' => false:

$args = array(
	'hide_empty' => false,
);

$cats = get_categories( $args ); // вернет все категории (включая пустые)

Заметки

  • Смотрите: get_terms() Type of arguments that can be changed.

Список изменений

С версии 2.1.0 Введена.

Код get_categories() WP 6.4.3

function get_categories( $args = '' ) {
	$defaults = array( 'taxonomy' => 'category' );
	$args     = wp_parse_args( $args, $defaults );

	/**
	 * Filters the taxonomy used to retrieve terms when calling get_categories().
	 *
	 * @since 2.7.0
	 *
	 * @param string $taxonomy Taxonomy to retrieve terms from.
	 * @param array  $args     An array of arguments. See get_terms().
	 */
	$args['taxonomy'] = apply_filters( 'get_categories_taxonomy', $args['taxonomy'], $args );

	// Back compat.
	if ( isset( $args['type'] ) && 'link' === $args['type'] ) {
		_deprecated_argument(
			__FUNCTION__,
			'3.0.0',
			sprintf(
				/* translators: 1: "type => link", 2: "taxonomy => link_category" */
				__( '%1$s is deprecated. Use %2$s instead.' ),
				'<code>type => link</code>',
				'<code>taxonomy => link_category</code>'
			)
		);
		$args['taxonomy'] = 'link_category';
	}

	$categories = get_terms( $args );

	if ( is_wp_error( $categories ) ) {
		$categories = array();
	} else {
		$categories = (array) $categories;
		foreach ( array_keys( $categories ) as $k ) {
			_make_cat_compat( $categories[ $k ] );
		}
	}

	return $categories;
}
26 комментариев
Полезные 1 Все
    Войти