REGISTER_META() │ WP 3.3.0

Функция register_meta() используется для регистрации мета-ключей (ключей пользовательских полей). Это нужно для использования мета-полей в различных API, например, в REST API. Также вы можете использовать эту функцию для добавления полей в мета-блоки с помощью add_meta_box().

Рекомендуется регистрировать мета-ключи для конкретной комбинации типа объекта и его подтипа. Если при регистрации не указать подтип, мета-ключ будет зарегистрирован для всего типа объекта. Однако его можно будет частично переопределить, если уже существует более специфичный мета-ключ с таким же именем для того же типа и подтипа.

Если тип объекта не поддерживает подтипы, например, для пользователей или комментариев, эту функцию лучше вызывать без указания подтипа.

Эта функция работает аналогично register_post_type(). Данные мета-полей хранятся в глобальной переменной $wp_meta_keys, что позволяет получать мета-данные в любом месте кода, что удобно для расширения функциональности.

Следует помнить, что регистрация в глобальной переменной доступна только с версии WP 4.6. Это значит, что функция и использующаяся технология начнут использоваться повсеместно с версии WordPress 4.6.

Как работать с мета-ключами

• Используйте get_registered_meta_keys() для получения данных всех зарегистрированных мета-полей.
• Пользуйтесь unregister_meta_key() для удаления ранее зарегистрированного мета-поля.

Возвращаемое значение

Функция может вернуть true или false.

• true — если мета-ключ успешно зарегистрирован в глобальном массиве $wp_meta_keys.
• false — если регистрация не удалась.

Использование функции

register_meta( $object_type, $meta_key, $args, $deprecated );

Параметры:

• $object_type (string) — обязательный параметр. Тип объекта, для которого регистрируется мета-ключ: post, user, comment, term. Это параметр $meta_type таких функций, как add/get/update/delete_metadata().

• $meta_key (string) — обязательный параметр. Имя ключа для регистрации.

• $args (array) — обязательный параметр. Данные, описывающие мета-поле. Значения по умолчанию:

$args = array(
    'object_subtype'    => '',
    'type'              => 'string',
    'description'       => '',
    'default'           => '',       // WP 5.5
    'single'            => false,
    'sanitize_callback' => null,
    'auth_callback'     => null,
    'show_in_rest'      => false,
);

• Описание параметров $args:

  • object_subtype (string) — конкретный тип объекта, для которого регистрируется мета-ключ. Например, если $object_type = post, то здесь можно указать название типа поста. По умолчанию: ''.

  • type (string) — тип значения мета-поля. Тип должен быть указан без сокращений:

  • string

  • boolean

  • integer

  • number

  • array (WP 5.3)

  • object (WP 5.3)

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

  • description (string) — описание данных в мета-поле.

  • single (bool) — обозначает, может ли быть только одно мета-поле с этим именем. true — только одно, false — множество.

  • default (string) (WP 5.5) — значение по умолчанию, которое возвращается функцией get_metadata(), если оно еще не установлено.

  • sanitize_callback (callable) — имя функции, к��торая будет использоваться для очистки значения мета-поля перед его сохранением в БД.

  • auth_callback (callable) — функция, которая будет вызываться при проверке прав доступа для редактирования, добавления и удаления мета-поля.

  • show_in_rest (bool) — должно ли это значение отображаться в REST-запросах. По умолчанию: false.

• $deprecated (string/array) — устаревший параметр с WP 4.6. Используйте $args вместо него.

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

Пример 1: Регистрация мета-поля для конкретного типа поста

С версии WordPress 4.9.8 функция поддерживает регистрацию метаданных не только для всего типа объекта, но и для конкретного подтипа. Для этого используется параметр object_subtype:

register_meta( 'post', 'my_meta_key', array(
    'object_subtype' => 'my_post_type',
    'show_in_rest' => true,
    'sanitize_callback' => 'absint',
) );

Теперь это мета-поле будет считаться мета-полем поста типа my_post_type.

Вы также можете зарегистрировать мета-поле для типа поста с помощью функции register_post_meta():

register_post_meta( 'my_post_type', 'my_meta_key', array(
    'show_in_rest' => true,
    'sanitize_callback' => 'absint',
) );

Пример 2: Демонстрация добавления мета-поля

Сначала зарегистрируем мета-поле и посмотрим, что было добавлено в глобальный массив:

register_meta( 'post', 'bookname', array(
    'type'              => 'string',
    'description'       => 'Название книги',
    'single'            => true,
    'sanitize_callback' => null,
    'auth_callback'     => null,
    'show_in_rest'      => false,
) );

global $wp_meta_keys;

print_r( $wp_meta_keys );

Вывод будет следующим:

Array
(
    [post] => Array
        (
            [bookname] => Array
                (
                    [type] => string
                    [description] => Название книги
                    [single] => 1
                    [sanitize_callback] =>
                    [auth_callback] => __return_true
                    [show_in_rest] =>
                )
        )
)

Пример 3: Регистрация мета-поля с функциями доступа и очистки

Регистрируем мета-поле с функциями для проверки прав и очистки данных:

register_meta( 'post', 'bookname', array(
    'type'              => 'string',
    'description'       => 'Название книги',
    'single'            => true,
    'sanitize_callback' => 'sanitize_bookname_meta',
    'auth_callback'     => 'auth_bookname_meta',
    'show_in_rest'      => false,
) );

function sanitize_bookname_meta( $meta_value, $meta_key, $object_type ){
    $meta_value = wp_strip_all_tags( $meta_value ); // Удаление html-тегов
    return $meta_value;
}

function auth_bookname_meta( $false, $meta_key, $postID, $user_id, $cap, $caps ){
    // Запрет на создание и редактирование этого мета-поля для всех, кроме администратора
    if( ! current_user_can('manage_options') )
        return false;

    return true;
}

Теперь, если вы зай��ете на страницу редактирования поста и попытаетесь создать мета-поле bookname, произойдет следующее:

• Если вы администратор, мета-поле будет создано.
• Если вы редактор или автор — создать мета-поле не получится.

Параметры auth_callback и sanitize_callback отвечают за это.

Изменения в версии

• 3.3.0 — Введена функция.
• 4.6.0 — Изменена для поддержки массива данных, прикрепляемого к зарегистрированным мета-ключам.
• 4.9.8 — Добавлен аргумент object_subtype.
• 5.3.0 — Расширены допустимые мета-типы до "array" и "object".
• 5.5.0 — Аргумент default добавлен в массив аргументов.
• 6.4.0 — Аргумент revisions_enabled добавлен в массив аргументов.

Related Functions

• add_comment_meta()
• add_metadata()
• add_post_meta()
• add_term_meta()
• add_user_meta()
• delete_comment_meta()
• delete_metadata()
• delete_post_meta()
• delete_term_meta()
• delete_user_meta()
• get_comment_meta()
• get_metadata()
• get_post_meta()
• get_user_meta()
• has_term_meta()
• is_protected_meta()
• register_post_meta()
• register_term_meta()
• sanitize_meta()