register_taxonomy() в WordPress: создание и настройка пользовательских таксономий

Функция register_taxonomy() позволяет создавать новые таксономии в WordPress или изменять уже существующие. Таксономии используются для группировки записей по определенным признакам. Это могут быть, например, категории или метки, а также произвольные таксономии, созданные разработчиками для расширения функционала.

register_taxonomy( string $taxonomy, array|string $object_type, array|string $args = array() ): WP_Taxonomy|WP_Error

Важно: не используйте эту функцию до хука init.

Параметры

1. $taxonomy — строка, ключ таксономии. Не может превышать 32 символов и должен состоять из строчных букв, цифр, дефисов и подчеркиваний.
2. $object_type — тип или массив типов объектов, для которых регистрируется таксономия. Например, 'post', 'page', или ваш собственный кастомный тип записей.
3. $args — массив аргументов, которые настраивают поведение таксономии. Ниже рассмотрим ключевые из них.

Аргументы $args:

• label (строка): Название таксономии во множественном числе для админки.
• description (строка): Краткое описание таксономии.
• labels (массив): Массив меток для отображения в интерфейсе.
  • name: Имя таксономии (обычно во множественном числе).
  • singular_name: Название для одного элемента.
  • menu_name: Название для меню.
  • search_items: Текст для поиска элементов.
  • popular_items: Популярные элементы.
  • all_items: Все элементы.
  • parent_item: Родительский элемент (для древовидных таксономий).
  • edit_item: Редактировать элемент.
  • update_item: Обновить элемент.
  • add_new_item: Добавить новый элемент.
  • view_item: Посмотреть элемент.
  • new_item_name: Название нового элемента.
  • separate_items_with_commas: Разделять элементы запятыми (не для древовидных).
  • add_or_remove_items: Добавить или удалить элементы.
  • choose_from_most_used: Выбрать из часто используемых.
  • not_found: Сообщение «не найдено».
  • back_to_items: Перейти к элементам.
• public (логический): Доступна ли таксономия для публичного использования.
• show_ui (логический): Отображать ли интерфейс для управления таксономией.
• show_in_menu (логический): Показывать ли таксономию в админ-меню.
• show_in_nav_menus (логический): Доступна ли таксономия в навигационном меню.
• show_tagcloud (логический): Показывать виджет облака тегов.
• show_in_rest (логический) (с WP 4.7): Включать ли таксономию в REST API.
• rest_base (строка) (с WP 4.7): Ярлык для REST API.
• rest_controller_class (строка) (с WP 4.7): Класс контроллера REST API.
• rest_namespace (строка) (с WP 5.9): Пространство имен в URL REST API маршрута.
• hierarchical (логический): Таксономия иерархическая (категории) или неиерархическая (теги).
• update_count_callback (строка): Название функции для подсчета терминов.
• rewrite (массив/false): Переписывать ли URL для таксономии.
  • slug: Часть URL для таксономии.
  • with_front: Включать ли префикс ссылки.
  • hierarchical: Древовидная структура ссылок.
  • ep_mask: Маска конечной точки для красивых ссылок.
• publicly_queryable (логический): Доступна ли таксономия для запросов на сайте.
• query_var (строка/логический): Параметр для запросов таксономии.
• capabilities (массив): Права доступа для управления таксономией.
  • manage_terms, edit_terms, delete_terms, assign_terms.
• meta_box_cb (строка): Callback-функция для отображения метабокса таксономии.
• meta_box_sanitize_cb (callable): Функция для очистки данных таксономии.
• show_admin_column (логический): Показать ли колонку таксономии в таблице постов.
• show_in_quick_edit (логический): Отображать ли таксономию в быстром редактировании.
• sort (логический): Запоминать ли порядок терминов при прикреплении к постам.
• default_term (строка/массив) (с WP 5.5): Термин по умолчанию.
• _builtin (логический): Внутренняя таксономия WordPress (не для обычного использования).

Избегайте зарезервированных терминов

При создании пользовательских таксономий важно избегать использования зарезервированных терминов WordPress, таких как category, tag, post, author, и других. Использование зарезервированных слов может вызвать конфликт и некорректную работу сайта.

• attachment
• attachment_id
• author
• author_name
• calendar
• cat
• category
• category__and
• category__in
• category__not_in
• category_name
• comments_per_page
• comments_popup
• 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__in
• post__not_in
• 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__and
• tag__in
• tag__not_in
• tag_id
• tag_slug__and
• tag_slug__in
• taxonomy
• tb
• term
• terms
• theme
• title
• type
• types
• w
• withcomments
• withoutcomments
• year

Пример 1: Создание таксономии для «Жанры фильмов»

В этом примере создается таксономия для записи типа movies, которая будет использоваться для классификации фильмов по жанрам. Важно отметить, что в этом примере также включена поддержка REST API.

add_action( 'init', 'create_movie_genre_taxonomy' );
function create_movie_genre_taxonomy() {
    register_taxonomy( 'movie_genre', ['movies'], [
        'labels' => [
            'name' => 'Movie Genres',
            'singular_name' => 'Movie Genre',
            'search_items' => 'Search Movie Genres',
            'all_items' => 'All Movie Genres',
            'edit_item' => 'Edit Movie Genre',
            'update_item' => 'Update Movie Genre',
            'add_new_item' => 'Add New Movie Genre',
            'new_item_name' => 'New Movie Genre Name',
            'menu_name' => 'Genres',
        ],
        'description' => 'Genres to classify different types of movies',
        'public' => true,
        'show_in_rest' => true,
        'hierarchical' => true, // Древовидная таксономия, как категории
        'rewrite' => [ 'slug' => 'movie-genre' ],
    ]);
}

Здесь:

• Таксономия называется movie_genre.
• Привязана к типу записи movies.
• Параметр hierarchical установлен в true, чтобы таксономия вела себя как древовидная структура (как категории).
• Включена поддержка REST API (show_in_rest => true), что делает таксономию доступной в редакторе блоков.

Пример 2: Таксономия для «Уровней сложности рецептов»

Теперь создадим таксономию для классификации рецептов по уровню сложности.

add_action( 'init', 'create_recipe_difficulty_taxonomy' );
function create_recipe_difficulty_taxonomy() {
    register_taxonomy( 'recipe_difficulty', ['recipes'], [
        'labels' => [
            'name' => 'Recipe Difficulty',
            'singular_name' => 'Difficulty Level',
            'search_items' => 'Search Difficulty Levels',
            'all_items' => 'All Difficulty Levels',
            'edit_item' => 'Edit Difficulty Level',
            'update_item' => 'Update Difficulty Level',
            'add_new_item' => 'Add New Difficulty Level',
            'new_item_name' => 'New Difficulty Level',
            'menu_name' => 'Difficulty Levels',
        ],
        'public' => true,
        'hierarchical' => false, // Таксономия недревовидная, как теги
        'show_in_rest' => true,
        'rewrite' => [ 'slug' => 'difficulty-level' ],
    ]);
}

Здесь таксономия recipe_difficulty недревовидная, что делает её аналогом меток (тегов).

Пример 3: Таксономия для «Тэгов книг»

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

add_action( 'init', 'create_book_tag_taxonomy' );
function create_book_tag_taxonomy() {
    register_taxonomy( 'book_tag', ['books'], [
        'labels' => [
            'name' => 'Book Tags',
            'singular_name' => 'Book Tag',
            'search_items' => 'Search Book Tags',
            'all_items' => 'All Book Tags',
            'edit_item' => 'Edit Book Tag',
            'update_item' => 'Update Book Tag',
            'add_new_item' => 'Add New Book Tag',
            'new_item_name' => 'New Book Tag',
            'menu_name' => 'Tags',
        ],
        'public' => true,
        'hierarchical' => false, // Таксономия будет недревовидной
        'show_in_rest' => true,
        'rewrite' => [ 'slug' => 'book-tag' ],
    ]);
}

Таксономия book_tag создана для типа записей books и будет использоваться для добавления тэгов к книгам.

Настройка прав доступа (capabilities)

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

add_action( 'init', 'create_special_taxonomy' );
function create_special_taxonomy() {
    register_taxonomy( 'special_category', ['post'], [
        'labels' => [
            'name' => 'Special Categories',
        ],
        'public' => true,
        'hierarchical' => true,
        'capabilities' => [
            'manage_terms' => 'manage_options', // Только администраторы могут управлять терминами
            'edit_terms' => 'manage_options',
            'delete_terms' => 'manage_options',
            'assign_terms' => 'edit_posts', // Редакторы могут назначать термины
        ],
        'rewrite' => [ 'slug' => 'special-category' ],
    ]);
}

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

Регистрация нескольких таксономий для конкретного типа записи

/**
 * Регистрация нескольких таксономий для типа записи 'book'.
 */
function wpdocs_create_multiple_taxonomies() {
    $taxonomies = array(
        array(
            'name' => 'Genre',
            'slug' => 'genre',
            'hierarchical' => true,
        ),
        array(
            'name' => 'Writer',
            'slug' => 'writer',
            'hierarchical' => false,
        ),
    );

    foreach ( $taxonomies as $taxonomy ) {
        register_taxonomy( $taxonomy['slug'], 'book', array(
            'label'        => __( $taxonomy['name'], 'textdomain' ),
            'rewrite'      => array( 'slug' => $taxonomy['slug'] ),
            'hierarchical' => $taxonomy['hierarchical'],
            'show_in_rest' => true,
        ) );
    }
}
add_action( 'init', 'wpdocs_create_multiple_taxonomies', 0 );

Заключение

Функция register_taxonomy() является мощным инструментом для создания и настройки таксономий в WordPress. Она позволяет группировать и структурировать данные с помощью произвольных категорий и меток, а также расширять функционал WordPress под конкретные нужды сайта.