Функция REGISTER_REST_FIELD() │ WP 4.7.0

Функция register_rest_field() позволяет добавить новое поле к существующему типу объекта в WordPress. Это полезно, если вы хотите расширить данные, которые возвращает ваш REST API.

Параметры

register_rest_field( $object_type, $attribute, $args );

• $object_type (string|array) (обязательный) — тип объекта, к которому привязывается поле, например: "post", "term", "comment" и т.д.
• $attribute (string) (обязательный) — имя добавляемого атрибута.
• $args (array) — массив аргументов для настройки поля.

Аргументы

По умолчанию array().

• get_callback (callable|null) — Функция, которая будет использоваться для получения значения поля. Функции передается подготовленные данные объекта. По умолчанию: null, поле не будет возвращено в ответе.

• update_callback (callable|null) — Функция, которая используется для задания и обновления значения поля. Функции передается объект модели, например, WP_Post. По умолчанию: null, значение не может быть установлено или обновлено.

• schema (array|null) — Схема для данного поля. По умолчанию: null, схема не будет возвращена.

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

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

Этот пример показывает, как создать поле, которое выводит имя автора поста.

add_action( 'rest_api_init', function() {
    register_rest_field( 'post', 'my_awesome_field', array(
        'get_callback' => function( $post, $field_name, $request ) {
            return get_the_author_meta( 'display_name', $post['author'] );
        },
        'update_callback' => null,
        'schema' => [
            'description' => __( 'Публичное имя пользователя', 'my_domain' ), 
            'type' => 'string'
        ],
    ) );
} );

Теперь вы можете ��айти поле my_awesome_field в JSON-ответе по адресу http://example.com/wp-json/wp/v2/posts.

Пример 2: Получение и обновление пользовательского поля поста

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

add_action( 'rest_api_init', 'slug_register_my_post_types' );

function slug_register_my_post_types() {
    register_rest_field( 'my_post_type', 'my_custom_field', [
        'get_callback'    => function( $object, $field_name, $request ) {
            return get_post_meta( $object['id'], $field_name );
        },
        'update_callback' => function( $value, $object, $field_name ) {
            return update_post_meta( $object->ID, $field_name, strip_tags( $value ) );
        },
        'schema'          => [
            'type'        => 'string',
            'arg_options' => [
                'sanitize_callback' => function( $value ) {
                    // Сделаем значение безопасным для хранения.
                    return sanitize_text_field( $value );
                },
                'validate_callback' => function( $value ) {
                    // Значение считается допустимым, если содержит ровно 10 английских букв.
                    return (bool) preg_match( '/A[a-z]{10}Z/', $value );
                },
            ],
        ],
    ]);
}

Запрос для получения постов, отсортированных по значению пользовательского поля:

GET https://myexample.com/wp-json/wp/v2/my_post_type?filter[meta_query][0][key]=my_custom_field&filter[meta_query][0][value]=my_find_value

Запрос для обновления значения пользовательского поля:

POST https://myexample.com/wp-json/wp/v2/my_post_type/{id}

где {id} — это идентификатор нужного поста.

Пример 3: Добавление поля с URL изображения поста

Этот пример показывает, как добавить поле для главного изображения в ответ данных поста.

add_action( 'rest_api_init', function () {
    register_rest_field( 'post', 'featured_image_url', array(
        'get_callback' => function ( $post_arr ) {
            $image_data = wp_get_attachment_image_src( $post_arr['featured_media'], 'medium' );
            return $image_data[0];
        },
        'update_callback' => null,
        'schema' => null
    ) );
} );

Параметры, передаваемые в функции обратного вызова

Для функции get_callback:

• $post — (объект) Объект запроса, например WP_Post.
• $attribute — (строка) Имя поля, указанное во втором параметре функции register_rest_field().
• $request — (объект) Все данные запроса в форме объекта WP_REST_Request.
• $object_type — (строка) Тип объекта, для которого зарегистрировано поле. Обычно соответствует значению первого параметра register_rest_field().

Для функции update_callback:

• $value — Значение из POST-запроса для текущего поля.
• $post — (объект) Объект запроса, например WP_Post.
• $attribute — (строка) Имя поля, указанное во втором параметре функции register_rest_field().
• $request — (объект) Все данные запроса в форме объекта WP_REST_Request.
• $object_type — (строка) Тип объекта, для которого зарегистрировано поле.

Замечания

• Глобальный массив: $wp_rest_additional_fields хранит зарегистрированные поля, организованные по типам объектов.

Изменения

Функция была введена в версии 4.7.0.