Как добавить пользовательское поле в REST API WordPress

REST API — одна из ключевых возможностей WordPress, позволяющая работать с данными сайта через HTTP-запросы. Однако стандартный REST API не всегда возвращает все необходимые пользовательские поля (custom fields), особенно если вы используете произвольные поля для расширения контента. В этой статье разберём, как добавить свои поля в REST API WordPress, чтобы они корректно отображались и были доступны для чтения и изменения.

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

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

Расширение REST API открывает возможности для:

• Создания кастомных фронтенд-приложений на React, Vue или других JS-фреймворках.
• Интеграции с внешними сервисами, которым нужны дополнительные данные.
• Управления пользовательскими полями через API, что удобно для мобильных приложений.

Давайте рассмотрим, как это сделать на примере.

Добавление пользовательского поля в REST API через функцию регистрации

Для добавления своего поля в REST API нужно использовать функцию register_rest_field. Она позволяет добавить новое поле к любому типу записи (например, post, page или кастомному типу).

Пример кода, который добавляет поле wpmart_custom_field к обычным постам:

function wpmart_register_custom_field() {
  register_rest_field('post', 'wpmart_custom_field', [
    'get_callback' => 'wpmart_get_custom_field',
    'update_callback' => 'wpmart_update_custom_field',
    'schema' => [
      'description' => 'Пользовательское поле WPMart',
      'type' => 'string',
      'context' => ['view', 'edit'],
    ],
  ]);
}

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

function wpmart_update_custom_field($value, $object) {
  if (!is_string($value)) {
    return new WP_Error('rest_invalid_param', 'Значение должно быть строкой', ['status' => 400]);
  }
  update_post_meta($object->ID, 'wpmart_custom_field', sanitize_text_field($value));
  return true;
}

add_action('rest_api_init', 'wpmart_register_custom_field');

В данном примере:

• register_rest_field добавляет поле wpmart_custom_field к REST API для записей типа post.
• get_callback возвращает значение метаполя.
• update_callback позволяет обновлять поле через PUT/PATCH запросы.
• schema описывает тип поля для документации API.

После добавления этого кода, при запросе /wp-json/wp/v2/posts в ответе будет поле wpmart_custom_field с нужным значением.

Особенности и рекомендации

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

• Обязательно проверяйте и фильтруйте данные, чтобы избежать уязвимостей.
• Если поле содержит сложные данные (массивы, объекты), указывайте в schema правильный тип и структуру.
• Для кастомных типов записей заменяйте post на ваш тип, например product или event.
• Можно использовать плагин Clearfy Pro, который упрощает работу с REST API, включая управление метаданными и оптимизацию.

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

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

function wpmart_register_multiple_fields() {
  $fields = ['wpmart_field_1', 'wpmart_field_2', 'wpmart_field_3'];
  foreach ($fields as $field) {
    register_rest_field('post', $field, [
      'get_callback' => function($object) use ($field) {
        return get_post_meta($object['id'], $field, true);
      },
      'update_callback' => function($value, $object) use ($field) {
        if (!is_string($value)) {
          return new WP_Error('rest_invalid_param', 'Значение должно быть строкой', ['status' => 400]);
        }
        update_post_meta($object->ID, $field, sanitize_text_field($value));
        return true;
      },
      'schema' => [
        'description' => 'Пользовательское поле ' . $field,
        'type' => 'string',
        'context' => ['view', 'edit'],
      ],
    ]);
  }
}
add_action('rest_api_init', 'wpmart_register_multiple_fields');

Такой подход удобен, если у вас много похожих полей, которые нужно добавить в API.

Примеры плагинов для работы с REST API и метаданными

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

• Advanced Custom Fields (ACF) to REST API — позволяет автоматически добавлять поля ACF в REST API.
• WP REST API Controller — удобный интерфейс для управления видимостью полей в API.
• Clearfy Pro — многофункциональный плагин для оптимизации и настройки WordPress, включая расширение REST API.

Тестирование и отладка новых полей в REST API

После добавления полей важно протестировать их работу. Для этого можно использовать:

• Плагины типа Postman или Insomnia — для отправки запросов и проверки ответов.
• Браузер — перейти по адресу https://ваш_сайт/wp-json/wp/v2/posts и проверить наличие новых полей.
• Инструменты разработчика в браузере для проверки запросов из фронтенд-приложения.

Если поля не отображаются, проверьте:

• Правильно ли подключен хук rest_api_init.
• Совпадает ли тип записи с тем, что вы указали.
• Отсутствие ошибок PHP — включите WP_DEBUG.

Выводы и полезные советы

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

Для большинства задач достаточно использовать register_rest_field, но при сложных структурах данных можно расширять schema и использовать кастомные функции в коллбэках.

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