register_taxonomy() │ WP 2.3.0

Создает новую произвольную таксономию WordPress. Позволяет изменить существующую таксономию.

Функция позволяет добавить (зарегистрировать) пользовательскую таксономию WP или поменять данные таксономии которая уже была зарегистрирована.

При изменении существующей таксономии значение параметра $object_type из первоначальной регистрации будет перезаписано. Поэтому, его важно указать заново такое же как было или новое.

add_action( 'init', 'function_name' );

attachment
attachment_id
author
author_name
calendar
cat
category
category_name
custom
customize_messenger_channel
customized
cpage
day
debug
embed
error
exact
feed
fields
hour
link_category
m
minute
monthnum
more
name
nav_menu
nonce
nopaging
offset
order
orderby
p
page
page_id
paged
pagename
pb
perm
post
post_format
post_mime_type
post_status
post_tag
post_type
posts
posts_per_archive_page
posts_per_page
preview
robots
s
search
second
sentence
showposts
static
status
subpost
subpost_id
tag
tag_id
taxonomy
tb
term
terms
theme
title
type
types
w
withcomments
withoutcomments
year

// правильный порядок регистрации типа записи и её таксономии
register_taxonomy( ... );
register_post_type( ... );

Возвращает

WP_Taxonomy|WP_Error. Зарегистрированный объект таксономии WP_Taxonomy при успехе, объект WP_Error при неудаче.

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

// хук для регистрации
add_action( 'init', 'create_taxonomy' );
function create_taxonomy(){

	// список параметров: wp-kama.ru/function/get_taxonomy_labels
	register_taxonomy( 'taxonomy', [ 'post' ], [
		'label'                 => '', // определяется параметром $labels->name
		'labels'                => [
			'name'              => 'Genres',
			'singular_name'     => 'Genre',
			'search_items'      => 'Search Genres',
			'all_items'         => 'All Genres',
			'view_item '        => 'View Genre',
			'parent_item'       => 'Parent Genre',
			'parent_item_colon' => 'Parent Genre:',
			'edit_item'         => 'Edit Genre',
			'update_item'       => 'Update Genre',
			'add_new_item'      => 'Add New Genre',
			'new_item_name'     => 'New Genre Name',
			'menu_name'         => 'Genre',
			'back_to_items'     => '← Back to Genre',
		],
		'description'           => '', // описание таксономии
		'public'                => true,
		// 'publicly_queryable'    => null, // равен аргументу public
		// 'show_in_nav_menus'     => true, // равен аргументу public
		// 'show_ui'               => true, // равен аргументу public
		// 'show_in_menu'          => true, // равен аргументу show_ui
		// 'show_tagcloud'         => true, // равен аргументу show_ui
		// 'show_in_quick_edit'    => null, // равен аргументу show_ui
		'hierarchical'          => false,

		'rewrite'               => true,
		//'query_var'             => $taxonomy, // название параметра запроса
		'capabilities'          => array(),
		'meta_box_cb'           => null, // html метабокса. callback: `post_categories_meta_box` или `post_tags_meta_box`. false — метабокс отключен.
		'show_admin_column'     => false, // авто-создание колонки таксы в таблице ассоциированного типа записи. (с версии 3.5)
		'show_in_rest'          => null, // добавить в REST API
		'rest_base'             => null, // $taxonomy
		// '_builtin'              => false,
		//'update_count_callback' => '_update_post_term_count',
	] );
}

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

register_taxonomy( $taxonomy, $object_type, $args );

$taxonomy(строка) (обязательный)

Название создаваемой таксономии (максимум 32 символа). Может содержать только строчные символы a-z, цифры 0-9, нижние подчёркивания _ и дефисы -. Регулярное выражение a-z0-9_- (определяется работой sanitize_key).

$object_type(строка/массив) (обязательный)

Название типов постов, к которым будет привязана таксономия.

В этом параметре, например, можно указать post, тогда у обычных постов WordPress появится новая таксономия.

Названия типов постов должны быть написаны в нижнем регистре и без пробелов. Максимальная разрешенная длина 20 символов.

• null – Установка null регистрирует таксономию, но не связывает ее ни с одним объектом, поэтому она не будет доступна в интерфейсе админ-панели. Связать объект и таксономию можно будет позднее при регистрации типа записи в параметре 'taxonomy': см. register_post_type() или с помощью register_taxonomy_for_object_type().

Встроенные типы постов WP:

• post
• page
• attachment
• revision
• nav_menu_item
• custom_css
• customize_changeset

$args(массив/строка/объект)

Аргументы (параметры) таксономии. Аргументы можно указать строкой, тогда они будут обработаны функцией wp_parse_args().
По умолчанию: array()

Аргументы параметра $args

• label (строка)
• description (строка)
• labels (массив)
• public (логический)
• show_ui (логический)
• show_in_menu (логический)
• show_in_nav_menus (логический)
• show_tagcloud (логический)
• show_in_rest (логический) (WP 4.7)
• rest_base (строка) (WP 4.7)
• rest_controller_class (строка) (WP 4.7)
• rest_namespace (строка) (WP 5.9)
• hierarchical (логический)
• update_count_callback (строка)
• rewrite (массив/false)
• publicly_queryable (логический)
• query_var (строка/логический)
• capabilities (массив)
• meta_box_cb (строка)
• meta_box_sanitize_cb (callable)
• show_admin_column (логический)
• show_in_quick_edit (логический)
• sort (логический)
• default_term (строка/массив) (с WP 5.5)
• _builtin (логический) (не для обычного использования)

label(строка)

Название таксономии во множественном числе (для отображения в админке).
По умолчанию: используется значение аргумента $labels->name

description(строка)

Короткое описание о таксономиии (для чего она).
По умолчанию: ''

labels(массив)

Массив описывающий заголовки таксономии (для отображения в админке).

Весь список смотрите в описании get_taxonomy_labels()

По умолчанию: используются заголовки "меток" для не древовидных типов таксономий и заголовки "категорий" для древовидных таксономий.

• name
  Имя таксономии, обычно во множественном числе. По умолчанию _x( 'Post Tags', 'taxonomy general name' ) или _x( 'Categories', 'taxonomy general name' );

• singular_name
  Название для одного элемента этой таксономии. По умолчанию _x( 'Post Tag', 'taxonomy singular name' ) или _x( 'Category', 'taxonomy singular name' );

• menu_name
  Текст для названия меню. Эта строка обозначает название для пунктов меню. По умолчанию значение параметра name;

• search_items
  Текст для поиска элемента таксономии. По умолчанию __( 'Search Tags' ) или __( 'Search Categories' );

• popular_items
  Текст для блока популярных элементов. __( 'Popular Tags' ) или null;

• all_items
  Текст для всех элементов. __( 'All Tags' ) или __( 'All Categories' );

• parent_item
  Текст для родительского элемента таксономии. Этот аргумент не используется для не древовидных таксономий. По умолчанию null или __( 'Parent Category' );

• parent_item_colon
  Текст для родительского элемента таксономии, тоже что и parent_item но с двоеточием в конце. По умолчанию нет или __( 'Parent Category:' );

• edit_item
  Текст для редактирования элемента. По умолчанию __( 'Edit Tag' ) или __( 'Edit Category' );

• update_item
  Текст для обновления элемента. По умолчанию __( 'Update Tag' ) или __( 'Update Category' );

• add_new_item
  Текст для добавления нового элемента таксономии. По умолчанию __( 'Add New Tag' ) или __( 'Add New Category' );

• view_item
  Текст для просмотра термина таксономии. По умолчанию: "Посмотреть метку", "Посмотреть категорию". Используется например, в админ баре (тулбаре).

• new_item_name
  Текст для создания нового элемента таксономии. По умолчанию __( 'New Tag Name' ) или __( 'New Category Name' );

• separate_items_with_commas
  Текст в админке говорящий что термины (метки) нужно разделять запятыми. Не используется для древовидных таксономий. По умолчанию: __( 'Separate tags with commas' ) или null.

• add_or_remove_items
  Текст для "удаления или добавления элемента", который используется в блоке админке, при отключенном javascript. Не действует для древовидных таксономий. По умолчанию __( 'Add or remove tags' ) или null;

• choose_from_most_used
  Текст для блога при редактировании поста "выберите из часто используемых". Не используется для древовидных таксономий. По умолчанию __( 'Choose from the most used tags' ) или null;

• popular_items
  Текст для поиска популярных терминов. Этот параметр не используется для древовидных таксономий. По умолчанию: "Популярные метки" или null.

• not_found
  Текст "не найдено", который отображается, если при клике на часто используемые ни один термин не был найден.

• back_to_items
  Текст "← Перейти к рубрикам". Метка, отображаемая после обновления термина.

public(логический)

Показывать ли эту таксономию в интерфейсе админ-панели. Это значение передается параметрам publicly_queryable, show_ui, show_in_nav_menus если для них не установлено свое значение.
По умолчанию: true

show_ui(логический)

Показывать блок управления этой таксономией в админке.
По умолчанию: если нет, равно аргументу public

show_in_menu(логический)

Показывать ли таксономию в админ-меню.

• true - таксономия будет показана как подменю у типа записи, к которой она прикреплена.
• false - подменю не будет показано.

Параметр $show_ui должен быть включен (true).

По умолчанию: если нет, равно аргументу show_ui

show_in_nav_menus(логический)

true даст возможность выбирать элементы этой таксономии в навигационном меню.
По умолчанию: если нет, равно аргументу public

show_tagcloud(логический)

Создать виджет облако элементов этой таксономии (как облако меток).
По умолчанию: если нет, равно аргументу show_ui

show_in_rest(логический) (WP 4.7)

Нужно ли включать таксономию в REST API.

Также влияет на работу блочного редактора Gutenberg:
true - таксономия будет видна в редакторе блоков Gutenberg
false - такса будет видна только в обычном редакторе.

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

rest_base(строка) (WP 4.7)

Ярлык в REST API. По умолчанию, название таксономии.
По умолчанию: $taxonomy

rest_controller_class(строка) (WP 4.7)

Название класса контроллера в REST API.
По умолчанию: 'WP_REST_Terms_Controller'

rest_namespace(строка) (WP 5.9)

Указывает префикс (пространство имен) в URL REST API маршрута.
По умолчанию: wp/v2

hierarchical(логический)

true - таксономия будет древовидная (иерархическая) - будет иметь checkbox'ы на странице редактирования поста (например категории поста).

false - таксономия будет не древовидная (Не-иерархическая) - будет иметь просто пустое текстовое поле для ввода имени элемента таксономии (например теги поста).

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

update_count_callback(строка)

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

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

• _update_post_term_count для таксономий прикрепленных к типам записей.
• _update_generic_term_count для таксономий, присоединенных к другим объектам, например, к юзерам.

Функция получит следующие параметры:

• $terms — term_taxonomy_id терминов которые нужно обновить.
• $taxonomy — Объект таксономии.

Подсчет выполняет функция wp_update_term_count_now(). Если таксономия прикреплена только к типам постов (она может быть еще прикреплена к юзерам), то будет использоваться функция _update_post_term_count(), которая будет считать только опубликованные посты связанные с термином. Если таксономия прикреплена не только к постам, то для подсчета будет использоваться _update_generic_term_count(), которая не делает такой проверки.

Это важно в случае с вложениями (attachments). Поскольку вложение - это тип сообщения, по умолчанию будет использоваться _update_post_term_count(). Однако это может работать не так как нужно, поскольку в этом случае будут учитываться только те вложения, которые прикреплены к посту (например, когда вы вставляете изображение в пост). Это означает, что вложения, которые вы просто загружаете в WordPress с помощью медиатеки, но фактически не прикрепляете к посту, не будут учтены при подсчете. Если вы собирались связать таксономию с вложениями, чтобы использовать медиатеку в качестве своего рода решения для управления документами, вам, вероятно, больше подойдет подсчет неприкрепленных медиа элементов, чем тех, которые прикреплены к постам. В этом случае вам следует принудительно использовать _update_generic_term_count(). Для этого нужно указать '_update_generic_term_count' в качестве значения для update_count_callback.

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

По умолчанию: '' - '_update_post_term_count' или '_update_generic_term_count'

rewrite(массив/false)

false - отключит перезапись. Если указать массив, то можно задать произвольный параметр запроса (query var). А по умолчанию будет использоваться параметр $taxonomy.

Возможные аргументы массива:

• slug(строка) - предваряет таксономии этой строкой. По умолчанию название таксономии.

• with_front(true/false) - позволяет установить префикс для постоянной ссылки. По умолчанию true.

• hierarchical(true/false) - true - включает поддержку древовидных URL.

  • Если true, то для древовидных таксономий ссылка на итем будет древовидной, например: /my-tax/parent-item/tax-item.
  • Если false, то ссылка не будет древовидной, даже если таксономия древовидная, например /my-tax/tax-item (когда элемент tax-item является дочерним). По умолчанию false.
• ep_mask(число) - Шаблон конечных точек. По умолчанию: EP_NONE. (Требуется для красивых пермалинков) Назначьте маску конечной точки для этой таксономии - по умолчанию EP_NONE. Если вы не укажете EP_MASK, красивые пермалинки работать не будут. Дополнительную информацию можно найти в статье Make WordPress Plugins summary of endpoints.

Массив передается в функцию add_permastruct(), поэтому тут также можно указать аргументы этой функции.

После изменения этого параметра или при первой регистрации таксономии, нужно пересоздать правила перезаписи. Это можно сделать вручную, просто перейдя на страницу Settings > Permalink. Или можно вызывать функцию flush_rewrite_rules(). Это нужно сделать всего один раз после регистрации таксономии, а не при каждом запросе.

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

publicly_queryable(логический)

Имеют ли пользователи доступ к элементам таксономии во внешней части сайта. Если не установлено, то берется значение параметра public. C версии 4.5.
По умолчанию: null (равен аргументу public)

query_var(строка/логический)

Если указать false, отключит параметры запроса и сам запрос. Т.е. WordPress не будет обрабатывать или понимать запросы связанные с этой таксономией.

Если указать строку, то она будет использовать в качестве параметра запроса, чтобы получить элементы этой таксономии. По умолчанию указывается название таксономии - параметр $taxonomy.

query_var используется для запросов через WP_Query, таких как:

new WP_Query( [ 'people' => $person_name ] )

и URL-запросов типа /?people=$person_name.

query_var=false отключит эти варианты, но вы все равно сможете получать посты с помощью явного запроса в WP_Query, например:

new WP_Query( [ 'taxonomy'=>'people', 'term'=>$person_name ] )

По умолчанию: $taxonomy

capabilities(массив)

Массив прав для этой таксономии:

• manage_terms - По умолчанию: manage_categories
• edit_terms - По умолчанию: manage_categories
• delete_terms - По умолчанию: manage_categories
• assign_terms - По умолчанию: edit_posts

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

meta_box_cb(строка)

callback функция. Отвечает за то, как будет отображаться таксономия в метабоксе (с версии 3.8).

Встроенные названия функций:

• post_categories_meta_box - показывать как категории
• post_tags_meta_box - показывать как метки.

Если указать false, то метабокс будет отключен вообще.

Данный параметр игнорируется при использовании Гутенберга.

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

meta_box_sanitize_cb(callable)

Коллбэк функция для очистки данных таксономии, сохраненных из мета-бокса. Если не установлена, то функция будет взята основываясь на значении $meta_box_cb.

show_admin_column(логический)

Позволить или нет авто-создание колонки таксономии в таблице ассоциированного типа записи. (с версии 3.5)
По умолчанию: false

show_in_quick_edit(логический)

Показывать ли таксономию в панели быстрого редактирования записи (в таблице, списке всех записей, при нажатии на кнопку "свойства"). С версии 4.2.
По умолчанию: null (значение show_ui)

sort(логический)

Следует ли этой таксономии запоминать порядок в котором созданные элементы (термины) прикрепляются к объектам (записям).

Например, для тегов, если этот параметр true, то при получении тегов они должны выводиться в том порядке, в котором они были указаны (добавлены) для записи. Т.е. если этот флаг установлен, то сортировка терминов должна быть не по name а по полю term_order.

При true в таблицу wp_term_relationships в поле term_order будет записываться число - порядок в котором расположены рубрики, в которые добавлена запись. Чаще всего эта настройка не нужна, более того, параметр этот есть, но в коде он нигде не прописан и по факту ни на что не виляет.
По умолчанию: null

default_term(строка/массив) (с WP 5.5)

Термин, который будет устанавливаться по умолчанию (если для записи не установлен никакой термин этой таксономии).

ID такого термина хранится в опции default_term_{$taxonomy_name}.

Можно указать массив, чтобы термин был создан, если его нет на сайте, см. wp_insert_term(). Возможные ключи массива:

• name(строка) - Имя дефолтного термина.
• slug(строка) - Ярлык (слаг) дефолтного термина.
• description(строка) - Описание для дефолтного термина.

_builtin(логический) (не для обычного использования)

Параметр предназначен для разработчиков. Если переключить на true, то это будет означать что эта таксономия относится к внутренним таксономия WordPress и не является (кастомной).
По умолчанию: false

Примеры

// хук, через который подключается функция
// регистрирующая новые таксономии (create_book_taxonomies)
add_action( 'init', 'create_book_taxonomies' );

// функция, создающая 2 новые таксономии "genres" и "writers" для постов типа "book"
function create_book_taxonomies(){

	// Добавляем древовидную таксономию 'genre' (как категории)
	register_taxonomy('genre', array('book'), array(
		'hierarchical'  => true,
		'labels'        => array(
			'name'              => _x( 'Genres', 'taxonomy general name' ),
			'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
			'search_items'      =>  __( 'Search Genres' ),
			'all_items'         => __( 'All Genres' ),
			'parent_item'       => __( 'Parent Genre' ),
			'parent_item_colon' => __( 'Parent Genre:' ),
			'edit_item'         => __( 'Edit Genre' ),
			'update_item'       => __( 'Update Genre' ),
			'add_new_item'      => __( 'Add New Genre' ),
			'new_item_name'     => __( 'New Genre Name' ),
			'menu_name'         => __( 'Genre' ),
		),
		'show_ui'       => true,
		'query_var'     => true,
		//'rewrite'       => array( 'slug' => 'the_genre' ), // свой слаг в URL
	));

	// Добавляем НЕ древовидную таксономию 'writer' (как метки)
	register_taxonomy('writer', 'book',array(
		'hierarchical'  => false,
		'labels'        => array(
			'name'                        => _x( 'Writers', 'taxonomy general name' ),
			'singular_name'               => _x( 'Writer', 'taxonomy singular name' ),
			'search_items'                =>  __( 'Search Writers' ),
			'popular_items'               => __( 'Popular Writers' ),
			'all_items'                   => __( 'All Writers' ),
			'parent_item'                 => null,
			'parent_item_colon'           => null,
			'edit_item'                   => __( 'Edit Writer' ),
			'update_item'                 => __( 'Update Writer' ),
			'add_new_item'                => __( 'Add New Writer' ),
			'new_item_name'               => __( 'New Writer Name' ),
			'separate_items_with_commas'  => __( 'Separate writers with commas' ),
			'add_or_remove_items'         => __( 'Add or remove writers' ),
			'choose_from_most_used'       => __( 'Choose from the most used writers' ),
			'menu_name'                   => __( 'Writers' ),
		),
		'show_ui'       => true,
		'query_var'     => true,
		//'rewrite'       => array( 'slug' => 'the_writer' ), // свой слаг в URL
	));
}

## Переименуем таксономию category (рубрики)
add_action( 'init', function(){
	global $wp_taxonomies;

	$labels                     = & $wp_taxonomies['category']->labels;
	$labels->name               = 'Author';
	$labels->singular_name      = 'Author';
	$labels->add_new            = 'Add Author';
	$labels->add_new_item       = 'Add Author';
	$labels->edit_item          = 'Edit Author';
	$labels->new_item           = 'Author';
	$labels->view_item          = 'View Author';
	$labels->search_items       = 'Search Authors';
	$labels->not_found          = 'No Authors found';
	$labels->not_found_in_trash = 'No Authors found in Trash';
	$labels->all_items          = 'All Authors';
	$labels->menu_name          = 'Author';
	$labels->name_admin_bar     = 'Author';

} );

Добавить свой пример