register_taxonomy()
Создает новую произвольную таксономию WordPress. Позволяет изменить существующую таксономию.
Функция позволяет добавить (зарегистрировать) пользовательскую таксономию WP или поменять данные таксономии которая уже была зарегистрирована.
При изменении существующей таксономии значение параметра $object_type из первоначальной регистрации будет перезаписано. Поэтому, его важно указать заново такое же как было или новое.
Таксономии - это возможность классифицировать объекты, например рубрики для постов. Читайте подробнее про таксономии.
Не рекомендуется вызвать функцию до хука-события init:
add_action( 'init', 'function_name' );
Зарезервированные названия
В названии таксономии (параметр $taxonomy) или в параметре query_var, нельзя использовать зарезервированные имена WordPress. Например, нельзя указывать author.
Это особенно важно, если вы передаете название через массив $_GET или $_POST. Это может привести к тому, что WordPress ответит ошибкой 404 без каких-либо других подсказок.
Полный список зарезервированных названий (черный список), которые нельзя использовать, в качестве имени новой таксономии или в параметрах относящихся к запросу.
Рекомендуется сначала регистрировать таксономию, а потом тип записи с которым эта таксономия связана!
Эта особенность в некоторых случаях избавит вас от багов и кучи потраченного времени.
// правильный порядок регистрации типа записи и её таксономии register_taxonomy( ... ); register_post_type( ... );
Привязать таксономию к типу записи можно попозже - после вызова этой функции, с помощью register_taxonomy_for_object_type().
Установите параметр show_in_rest = true, чтобы панель таксономии появилась на боковой панели редактора блоков.
Используйте register_post_type(), когда нужно зарегистрировать новый тип записи.
Удобный плагин, который позволяет регистрировать новые типы записей и таксономии: Custom Post Type UI
Хуки из функции
Возвращает
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(строка)
- Название таксономии во множественном числе (для отображения в админке).
По умолчанию: используется значение аргумента $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 - publicly_queryable(логический)
- Имеют ли пользователи доступ к элементам таксономии во внешней части сайта. Если не установлено, то берется значение параметра public. C версии 4.5.
По умолчанию: null (равен аргументу public) - show_ui(логический)
- Показывать блок управления этой таксономией в админке.
По умолчанию: если нет, равно аргументу public Показывать ли таксономию в админ-меню.
- true - таксономия будет показана как подменю у типа записи, к которой она прикреплена.
- false - подменю не будет показано.
Параметр $show_ui должен быть включен (true).
По умолчанию: если нет, равно аргументу show_ui
- 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().
В зависимости от типа таксономии, WordPress использует разные функции для подсчёта количества объектов, связанных с терминами:
- Если таксономия связана только с типами записей, используется функция:
_update_post_term_count() ― Считает только опубликованные посты, связанные с термином. - Если таксономия прикреплена не только к постам, то для подсчета будет использоваться _update_generic_term_count() ― Не делает проверку на статус публикации.
Важно в случае с вложениями (attachments).
Поскольку вложения — это тип записи, по умолчанию используется _update_post_term_count().
Это означает:
-
Считаются только вложения, прикреплённые к постам (например, изображения в теле записи).
- Вложения, загруженные в медиатеку, но не прикреплённые к постам, не учитываются.
Если вы используете таксономии для управления медиатекой (например, как систему управления документами), вам может быть важен учёт всех загруженных файлов, включая неприкреплённые.
В этом случае следует вручную указать функцию подсчёта:
'update_count_callback' => '_update_generic_term_count'
Функция _update_post_term_count() учитывает только опубликованные посты (со статусом publish).
Чтобы добавить и другие статусы в подсчет используйте хук update_post_term_count_statuses. Или создайте и укажите в этом параметре свою функцию подсчета.
По умолчанию: '' (_update_post_term_count() / _update_generic_term_count())
- rewrite(массив/false)
false - отключит перезапись. Если указать массив, то можно задать произвольный параметр запроса (query var). А по умолчанию будет использоваться параметр $taxonomy.
Возможные аргументы массива:
-
slug(строка) - предваряет таксономии этой строкой.
По умолчанию: ярлык таксономии
-
with_front(true/false) - указывает, добавлять ли к slug базовый префикс permalink.
Это префикс берется из настройки ЧПУ в админке:
settings > permalink. Например, если установлена структура/blog/%postname%/, то :with_front => true: /blog/my-tax/termwith_front => false: /my-tax/term
По умолчанию 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
-
- 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_categoriesedit_terms- По умолчанию:manage_categoriesdelete_terms- По умолчанию:manage_categoriesassign_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
Примеры
#1 Регистрация таксономий
Пример регистрации двух таксономий "genres" и "writers" для постов типа "book". Этот код можно вставить в файл темы functions.php. Некоторые аргументы рассчитаны на версию 3.1+:
// хук, через который подключается функция
// регистрирующая новые таксономии (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
));
} #2 Добавление таксономии в ЧПУ
Смотрите в примерах к описаниям функций: register_post_type(), WP_Rewrite
#3 Переименования названий таксономии
Код ниже, показывает как переименовать имеющуюся таксономию category (рубрики).
## Переименуем таксономию 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';
} );
Заметки
- Global. WP_Taxonomy[]. $wp_taxonomies Registered taxonomies.
Список изменений
| С версии 2.3.0 | Введена. |
| С версии 4.2.0 | Introduced show_in_quick_edit argument. |
| С версии 4.4.0 | The show_ui argument is now enforced on the term editing screen. |
| С версии 4.4.0 | The public argument now controls whether the taxonomy can be queried on the front end. |
| С версии 4.5.0 | Introduced publicly_queryable argument. |
| С версии 4.7.0 | Introduced show_in_rest, 'rest_base' and 'rest_controller_class' arguments to register the taxonomy in REST API. |
| С версии 5.1.0 | Introduced meta_box_sanitize_cb argument. |
| С версии 5.4.0 | Added the registered taxonomy object as a return value. |
| С версии 5.5.0 | Introduced default_term argument. |
| С версии 5.9.0 | Introduced rest_namespace argument. |