Полное руководство по функции register_post_type() в WordPress.

Функция register_post_type() в WordPress используется для создания пользовательских типов записей (Custom Post Types), которые позволяют расширить стандартные возможности WordPress и адаптировать его под нужды вашего сайта. Это особенно полезно для создания нестандартных разделов контента, таких как портфолио, отзывы, мероприятия и т.д.

register_post_type( string $post_type, array|string $args = array() ): WP_Post_Type|WP_Error

Параметры

• $post_type (string) — Имя типа записи. Оно должно быть уникальным и обычно состоит из строчных букв и дефисов (например, portfolio или testimonial). Нельзя использовать следующие названия для новых типов постов (они уже используются в WordPress и будут конфликтовать):
  • post
  • page
  • attachment
  • revision
  • nav_menu_item
  • custom_css
  • customize_changeset
  • action
  • author
  • order
  • theme

• $args (array) — Массив параметров, определяющих характеристики пользовательского типа записи. Это ключевые настройки, такие как метки, поддерживаемые функции и многое другое.

Важное по register_post_type()

• Для правильной работы функции register_post_type(), важно, чтобы она вызывалась в момент выполнения хука init. Если функцию подключить до этого хука, тип записи не будет создан, а если после, то он может функционировать некорректно.

• При создании нового типа записи обязательно указывайте уникальное имя, которое не совпадает с уже существующими таксономиями, другими типами записей или зарезервированными переменными WordPress. Это поможет избежать конфликтов и ошибок.

• Обратите внимание: после регистрации нового типа записи необходимо зайти в раздел Настройки → Постоянные ссылки в админке WordPress. Это позволит пересоздать правила ЧПУ (человекопонятных урлов) и добавить туда правила для нового типа записи.

• С версии 4.6 WordPress ввел новый класс WP_Post_Type, который теперь обрабатывает весь код функции register_post_type(). Эта функция теперь является лишь оберткой для нового класса.

• Если для вашего нового типа записи планируется использование таксономии, регистрируйте эту таксономию одновременно с типом записи, используя параметр taxonomies. В противном случае, тип записи и таксономия могут не связываться правильно при срабатывании таких хуков, как parse_query или pre_get_posts, что может привести к непредвиденным проблемам.
  
  Таксономии следует регистрировать отдельно. Хотя их можно указать при регистрации типа записи, саму таксономию нужно регистрировать отдельно с помощью функции register_taxonomy().
  
  Следуйте правильному порядку регистрации: сначала регистрируйте таксономию, а затем тип записи, к которому эта таксономия привязана. Это поможет избежать ошибок и сократит время на устранение проблем.

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

Параметры аргумента $args при регистрации типа записи

При регистрации нового типа записи в WordPress, вы можете настроить его поведение и внешний вид через массив аргументов $args. Эти аргументы контролируют различные аспекты работы типа записи, от отображения в админ-панели до доступности через REST API. Давайте рассмотрим каждый из них:

label (строка)

Описание: Задает имя типа записи, которое будет использоваться для перевода на другой язык. Это значение является основным идентификатором типа записи и используется для создания отдельного шаблона вывода.

По умолчанию: Значение параметра $post_type.

Примечание: Без указания свойства label не получится создать отдельный шаблон для кастомного типа записи.

labels (массив)

Описание: Массив, содержащий различные названия ярлыков для типа записи. Это позволяет настроить все тексты, связанные с типом записи, такие как «Добавить новый», «Редактировать», «Просмотреть» и другие.

Ключи массива и их значения:

• 'name' — Основное название для типа записи, обычно во множественном числе.
• 'singular_name' — Название для одной записи этого типа.
• 'add_new' — Текст для добавления новой записи (например, «Добавить новый»).
• 'add_new_item' — Заголовок для новой записи в админ-панели.
• 'edit_item' — Текст для редактирования записи.
• 'new_item' — Текст для новой записи.
• 'view_item' — Текст для просмотра записи.
• 'search_items' — Текст для поиска по этому типу записи.
• 'not_found' — Текст, если ничего не найдено.
• 'not_found_in_trash' — Текст, если ничего не найдено в корзине.
• 'parent_item_colon' — Текст для родительских записей (не используется для не древовидных типов записей).
• 'all_items' — Текст для отображения всех записей.
• 'archives' — Текст для архивов записей.
• 'insert_into_item' — Текст для вставки в запись.
• 'uploaded_to_this_item' — Текст для загруженных в запись файлов.
• 'featured_image' — Текст для миниатюры записи.
• 'set_featured_image' — Текст для установки миниатюры записи.
• 'remove_featured_image' — Текст для удаления миниатюры записи.
• 'use_featured_image' — Текст для использования изображения как миниатюры записи.
• 'filter_items_list' — Текст для фильтрации списка записей.
• 'items_list_navigation' — Текст для навигации по списку записей.
• 'items_list' — Текст для списка записей.
• 'menu_name' — Название меню, по умолчанию равно 'name'.
• 'name_admin_bar' — Название в админ-баре, по умолчанию равно 'singular_name'.
• 'view_items' — Название в тулбаре для страницы архива типа записей (с WP 4.7).
• 'attributes' — Название для метабокса атрибутов записи (с WP 4.7).
• 'item_updated' — Текст уведомления при обновлении записи (с WP 5.0).
• 'item_published' — Текст уведомления при публикации записи (с WP 5.0).
• 'item_published_privately' — Текст уведомления при публикации частной записи (с WP 5.0).
• 'item_reverted_to_draft' — Текст уведомления при возврате записи в черновики (с WP 5.0).
• 'item_scheduled' — Текст уведомления при запланированной публикации записи (с WP 5.0).

По умолчанию: Если не установлено, значения name и singular_name будут использоваться как значения для label.

description (строка)

Описание: Краткое описание типа записи, которое используется в REST API. Вы можете получить это значение с помощью функции get_the_post_type_description().

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

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

Описание: Определяет, является ли тип записи публичным. Этот параметр управляет несколькими другими опциями:

• false: show_ui = false, publicly_queryable = false, exclude_from_search = true, show_in_nav_menus = false.
• true: show_ui = true, publicly_queryable = true, exclude_from_search = false, show_in_nav_menus = true.

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

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

Описание: Определяет, могут ли URL запросы для этого типа записи быть доступны на фронт-энде. Если установлено в true, URL будут работать как /book/my-book-name, в противном случае запросы вернут 404 страницу.

По умолчанию: Значение параметра public.

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

Описание: Определяет, будет ли тип записи исключен из поисковых запросов сайта. Если установлено в true, записи этого типа не будут учитываться при поиске.

По умолчанию: Обратное значение параметра public.

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

Описание: Определяет, нужно ли отображать пользовательский интерфейс для управления этим типом записи в админ-панели.

По умолчанию: Значение параметра public.

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

Описание: Указывает, следует ли отображать тип записи в администраторском меню.

• false — не показывать.
• true — показывать как меню первого уровня.
• Строка — показывать как подменю в меню первого уровня.

По умолчанию: Значение параметра show_ui.

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

Описание: Определяет, будет ли тип записи доступен в админ-баре.

По умолчанию: Значение параметра show_in_menu.

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

Описание: Указывает, можно ли выбирать этот тип записи в меню навигации.

По умолчанию: Значение параметра public.

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

Описание: Определяет, должен ли тип записи быть доступен через REST API. Если установлено в true, тип записи будет доступен по маршруту wp/v2.

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

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

Описание: Ярлык для REST API. По умолчанию используется название типа записи.

По умолчанию: Значение $post_type.

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

Описание: Указывает класс контроллера для REST API.

По умолчанию: 'WP_REST_Posts_Controller'.

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

Описание: Указывает префикс (пространство имен) в URL REST API маршрута.

По умолчанию: 'wp/v2'.

menu_position (число)

Описание: Определяет позицию меню для нового типа записи. Значение может варьироваться от 1 до 100+, указывающее место в администраторском меню.

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

menu_icon (строка)

Описание: Указывает иконку для меню типа записи. Может быть ссылкой на изображение или названием иконки из пакета Dashicons.

Примеры:

• 'dashicons-admin-post' — иконка Dashicons.
• get_template_directory_uri() .'/images/icon.png' — ссылка на изображение.
• 'data:image/svg+xml;base64,' . base64_encode('<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><path fill="black" /></svg>') — SVG иконка в base64 формате.
• 'none' — класс .wp-menu-image empty, который позволяет установить иконку через CSS.

По умолчанию: null (иконка по умолчанию).

capability_type (строка/массив)

Описание: Определяет маркер для установки прав для типа записи. Можно использовать как строку, так и массив.

Примеры:

• 'post' — стандартный тип записи.
• 'page' — тип страницы.
• 'custom_type' — кастомный тип записи.
• 'custom_type' (массив) — допустимо указать разные права, например, array('custom_type', 'custom_types').

По умолчанию: 'post'.

capabilities (массив)

Описание: Позволяет переопределить стандартные права доступа для кастомного типа записи.

Пример:

'capabilities' => array(
    'edit_post'             => 'edit_custom_type',
    'read_post'             => 'read_custom_type',
    'delete_post'           => 'delete_custom_type',
    'edit_posts'            => 'edit_custom_types',
    'edit_others_posts'     => 'edit_others_custom_types',
    'delete_posts'          => 'delete_custom_types',
    'delete_others_posts'   => 'delete_others_custom_types',
    'publish_posts'         => 'publish_custom_types',
    'read_private_posts'    => 'read_private_custom_types',
)

По умолчанию: Права по умолчанию для типа записи.

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

Описание: Определяет, должны ли быть сопоставлены права доступа для типа записи. Если установлено в true, разрешения будут сопоставлены с пользовательскими правами.

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

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

Описание: Определяет, имеет ли тип записи иерархию (как страницы). Если установлено в true, записи могут иметь родителей и дочерние записи.

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

supports (массив)

Описание: Определяет функциональность, которую будет поддерживать тип записи. Возможные значения включают:

• 'title' — заголовок.
• 'editor' — визуальный редактор.
• 'author' — автор.
• 'thumbnail' — миниатюра.
• 'excerpt' — краткое содержание.
• 'trackbacks' — трекбэки.
• 'custom-fields' — произвольные поля.
• 'comments' — комментарии.
• 'revisions' — ревизии.
• 'page-attributes' — атрибуты страницы (для иерархических типов записей).

Пример:

'supports' => array('title', 'editor', 'thumbnail')

По умолчанию: Зависит от типа записи. Обычно 'title' и 'editor'.

taxonomies (массив)

Описание: Позволяет назначить таксономии для типа записи. Это может быть стандартные таксономии (категории, теги) или кастомные таксономии.

Пример:

'taxonomies' => array('category', 'post_tag')

По умолчанию: Пустой массив.

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

Описание: Определяет, нужно ли создать архив для типа записи. Если установлено в true, архив будет доступен по URL /post-type/. Также можно указать строку, чтобы задать собственный слаг для архива.

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

rewrite (массив/логический)

Описание: Позволяет настроить правила перезаписи (чпу) для типа записи. Массив может содержать параметры slug, with_front, pages, feeds и другие.

Пример:

'rewrite' => array(
    'slug' => 'books',
    'with_front' => true,
    'pages' => true,
    'feeds' => true,
)

По умолчанию: true (если параметр public установлен в true).

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

Описание: Определяет, будет ли тип записи использовать переменную запроса. Можно задать строку для имени переменной, или установить в false, чтобы отключить использование переменной запроса.

По умолчанию: Значение параметра $post_type.

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

Описание: Определяет, можно ли экспортировать записи этого типа через инструмент экспорта WordPress.

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

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

Описание: Определяет, должен ли тип записи быть доступен через REST API.

По умолчанию: Значение параметра public.

Пример использования

Ниже приведен пример кода, который регистрирует новый тип записи «Portfolio» с поддержкой заголовка, описания и миниатюры.

function create_portfolio_post_type() {
    $labels = array(
        'name'               => _x( 'Portfolios', 'post type general name', 'textdomain' ),
        'singular_name'      => _x( 'Portfolio', 'post type singular name', 'textdomain' ),
        'menu_name'          => _x( 'Portfolios', 'admin menu', 'textdomain' ),
        'name_admin_bar'     => _x( 'Portfolio', 'add new on admin bar', 'textdomain' ),
        'add_new'            => _x( 'Add New', 'portfolio', 'textdomain' ),
        'add_new_item'       => __( 'Add New Portfolio', 'textdomain' ),
        'new_item'           => __( 'New Portfolio', 'textdomain' ),
        'edit_item'          => __( 'Edit Portfolio', 'textdomain' ),
        'view_item'          => __( 'View Portfolio', 'textdomain' ),
        'all_items'          => __( 'All Portfolios', 'textdomain' ),
        'search_items'       => __( 'Search Portfolios', 'textdomain' ),
        'parent_item_colon'  => __( 'Parent Portfolios:', 'textdomain' ),
        'not_found'          => __( 'No portfolios found.', 'textdomain' ),
        'not_found_in_trash' => __( 'No portfolios found in Trash.', 'textdomain' ),
    );

    $args = array(
        'labels'             => $labels,
        'public'             => true,
        'has_archive'        => true,
        'supports'           => array( 'title', 'editor', 'thumbnail' ),
        'rewrite'            => array( 'slug' => 'portfolio' ),
        'show_ui'            => true,
    );

    register_post_type( 'portfolio', $args );
}

add_action( 'init', 'create_portfolio_post_type' );

Пояснение к коду

1. Функция create_portfolio_post_type() — Определяет параметры для нового типа записи «Portfolio».
2. Массив $labels — Содержит все метки, которые будут отображаться в административной панели WordPress.
3. Массив $args — Устанавливает основные настройки, такие как публичность, поддерживаемые функции и архив.
4. register_post_type() — Регистрирует новый тип записи с указанными параметрами.
5. add_action( 'init', 'create_portfolio_post_type' ) — Подключает функцию к хук init, чтобы тип записи был зарегистрирован при инициализации WordPress.

Пример 2: Добавление таксономии в ЧПУ для типа записи «tutorial»

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

URL для записи: example.com/tutorial/{категория}/{ярлык-записи}
URL для таксономии: example.com/tutorial/{категория}

// Регистрация таксономии
add_action('init', 'register_tutorial_taxonomy_and_post_type');

function register_tutorial_taxonomy_and_post_type() {
    // Регистрация таксономии для учебных пособий
    register_taxonomy('tutorial_category', ['tutorial_item'], [
        'label'                 => 'Категория Учебных Пособий',
        'labels'                => [
            'name'              => 'Категории Учебных Пособий',
            'singular_name'     => 'Категория Учебного Пособия',
            'search_items'      => 'Искать Категорию Учебного Пособия',
            'all_items'         => 'Все Категории Учебных Пособий',
            'parent_item'       => 'Родительская Категория Учебного Пособия',
            'edit_item'         => 'Редактировать Категорию Учебного Пособия',
            'update_item'       => 'Обновить Категорию Учебного Пособия',
            'add_new_item'      => 'Добавить Новую Категорию Учебного Пособия',
            'new_item_name'     => 'Название Новой Категории Учебного Пособия',
            'menu_name'         => 'Категория Учебных Пособий',
        ],
        'description'           => 'Категории для учебных пособий',
        'public'                => true,
        'show_ui'               => true,
        'show_in_nav_menus'     => false,
        'hierarchical'          => true,
        'rewrite'               => ['slug' => 'tutorial', 'hierarchical' => false],
        'show_admin_column'     => true,
    ]);

    // Регистрация типа записи "tutorial_item"
    register_post_type('tutorial_item', [
        'label'               => 'Учебные Пособия',
        'labels'              => [
            'name'          => 'Учебные Пособия',
            'singular_name' => 'Учебное Пособие',
            'menu_name'     => 'Учебные Пособия',
            'all_items'     => 'Все Учебные Пособия',
            'add_new'       => 'Добавить Новое Учебное Пособие',
            'edit_item'     => 'Редактировать Учебное Пособие',
            'new_item'      => 'Новое Учебное Пособие',
        ],
        'public'              => true,
        'show_ui'             => true,
        'rewrite'             => ['slug' => 'tutorial/%tutorial_category%', 'with_front' => false],
        'has_archive'         => 'tutorial',
        'supports'            => ['title', 'editor'],
        'taxonomies'          => ['tutorial_category'],
    ]);
}

function custom_tutorial_permalink($permalink, $post) {
    if (strpos($permalink, '%tutorial_category%') === false) {
        return $permalink;
    }

    $terms = get_the_terms($post, 'tutorial_category');
    $term_slug = (!is_wp_error($terms) && !empty($terms) && is_object($terms[0])) ? $terms[0]->slug : 'no-category';

    return str_replace('%tutorial_category%', $term_slug, $permalink);
}
add_filter('post_type_link', 'custom_tutorial_permalink', 10, 2);

Заключение по register_post_type()

Функция register_post_type() позволяет гибко управлять контентом на вашем сайте, создавая типы записей, которые соответствуют вашим требованиям и предоставляют удобный способ для их управления.