Как добавить пользовательские поля в WordPress REST API: практическое руководство

Понимание задачи: зачем расширять WordPress REST API пользовательскими полями

По умолчанию WordPress REST API возвращает стандартный набор данных о постах, страницах и других типах записей. Однако часто возникает необходимость получить дополнительные данные, которые хранятся в пользовательских полях (custom fields, мета-полях). Например, для мобильных приложений, SPA на React или Vue, интеграций с внешними сервисами важно иметь полный набор данных в одном запросе.

Без расширения API вам придётся делать дополнительные запросы к метаданным, что увеличивает нагрузку и усложняет логику на клиенте. Поэтому правильное добавление пользовательских полей в ответ API — это оптимальный и удобный способ решения задачи.

В этой статье мы разберём, как добавить пользовательские мета-поля в ответ REST API WordPress, рассмотрим безопасность и примеры кода с использованием хуков WordPress.

Добавление пользовательских полей через register_rest_field

Ключевой механизм для добавления новых полей в REST API WordPress — функция register_rest_field(). С её помощью можно определить новое поле, указать функцию для получения значений и, при необходимости, функцию для сохранения значения.

Рассмотрим пример: допустим, у нас есть мета-поле с ключом _wpmark_price, в котором хранится цена товара (если сайт — магазин на базе WooCommerce или кастомного решения).

Для добавления этого поля в REST API добавим следующий код в файл functions.php вашей темы или в отдельный плагин:

add_action('rest_api_init', function () {
    register_rest_field('post', 'wpmark_price', [
        'get_callback' => 'wpmark_get_price_meta',
        'update_callback' => 'wpmark_update_price_meta',
        'schema' => [
            'description' => 'Цена товара',
            'type' => 'number',
            'context' => ['view', 'edit'],
        ],
    ]);
});

function wpmark_get_price_meta($object) {
    return get_post_meta($object['id'], '_wpmark_price', true);
}

function wpmark_update_price_meta($value, $object, $field_name) {
    if (!is_numeric($value)) {
        return new WP_Error('rest_invalid_price', 'Цена должна быть числом.', ['status' => 400]);
    }
    return update_post_meta($object->ID, '_wpmark_price', $value);
}

Объяснение работы:

При инициализации REST API (хук rest_api_init) регистрируется новое поле wpmark_price для типа записей post.
get_callback возвращает значение мета-поля _wpmark_price.
update_callback отвечает за сохранение значения, с проверкой, что цена — число.
schema описывает поле для автоматической генерации документации и валидации.

Проверка результата

Теперь, сделав GET-запрос к REST API, например, /wp-json/wp/v2/posts/123, вы увидите в ответе новое поле wpmark_price с ценой товара.

Также, отправляя PATCH или POST-запрос с полем wpmark_price, можно обновить это значение через API.

Как добавить несколько пользовательских полей и оптимизировать код

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

add_action('rest_api_init', function () {
    $meta_fields = [
        'wpmark_price' => '_wpmark_price',
        'wpmark_rating' => '_wpmark_rating',
        'wpmark_color' => '_wpmark_color',
    ];

    foreach ($meta_fields as $field_name => $meta_key) {
        register_rest_field('post', $field_name, [
            'get_callback' => function ($object) use ($meta_key) {
                return get_post_meta($object['id'], $meta_key, true);
            },
            'update_callback' => function ($value, $object) use ($meta_key) {
                return update_post_meta($object->ID, $meta_key, sanitize_text_field($value));
            },
            'schema' => [
                'type' => 'string',
                'context' => ['view', 'edit'],
            ],
        ]);
    }
});

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

Важные моменты безопасности при работе с пользовательскими полями в REST API

Добавляя пользовательские поля в REST API, не забывайте про безопасность и права доступа. Не все мета-поля должны быть доступны всем пользователям.

Чтобы ограничить доступ, используйте ключ permission_callback в register_rest_field:

register_rest_field('post', 'wpmark_price', [
    'get_callback' => 'wpmark_get_price_meta',
    'update_callback' => 'wpmark_update_price_meta',
    'permission_callback' => function () {
        return current_user_can('edit_posts');
    },
    'schema' => [...],
]);

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

Если поле нужно показывать всем, но редактировать только администраторам, можно упростить проверку для GET-запросов и усложнить для PUT/PATCH.

Использование пользовательских типов записей и мета-полей в REST API

Если у вас есть кастомные типы записей, например product, добавлять пользовательские поля нужно аналогично, только регистрировать для нужного типа:

register_rest_field('product', 'wpmark_custom_meta', [
    'get_callback' => 'wpmark_get_custom_meta',
    'update_callback' => 'wpmark_update_custom_meta',
    'permission_callback' => function () {
        return current_user_can('edit_products');
    },
    'schema' => [...],
]);

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

Выводы и советы для разработчиков

Всегда проверяйте права пользователя через permission_callback, чтобы не раскрывать чувствительные данные.
Используйте sanitize_text_field и другие функции очистки данных при сохранении.
Документируйте добавленные поля, чтобы другие разработчики понимали структуру API.
Тестируйте API с помощью Postman или аналогов, проверяйте работу GET, POST, PATCH запросов.
Если нужно добавить поля для REST API коллекций (например, список постов), убедитесь, что поля добавляются для каждого объекта корректно.

Таким образом, расширение WordPress REST API пользовательскими полями — это удобный инструмент для передачи сложных данных между вашим сайтом и внешними приложениями. Приведённые примеры помогут быстро начать и избежать типичных ошибок.