Функция rest_ensure_response() в WordPress

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

rest_ensure_response( $response )

Эта функция проверяет переданные данные и при необходимости преобразует их в объект WP_REST_Response. Этот объект предоставляет ряд методов, таких как set_status(), set_headers(), и set_data(), которые вы можете использовать для настройки ответа API.

Использование этой функции также позволяет WordPress автоматически обрабатывать любые данные, возвращаемые из коллбек-функции, зарегистрированной с помощью register_rest_route(). Например, если ваша коллбек-функция возвращает строку, эта строка будет преобразована в объект WP_REST_Response благодаря rest_ensure_response().

Параметры

• $response (смешанный) — Данные, которые нужно преобразовать в объект ответа REST API. Это может быть массив, объект WP_Error, объект WP_REST_Response или любая другая строка или число.

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

• WP_REST_Response|WP_Error — Объект ответа REST API или объект ошибки.

Функция rest_ensure_response() возвращает либо объект WP_REST_Response, либо объект WP_Error, в зависимости от переданных данных:

• Если передан объект WP_Error, функция возвращает его как есть.
• Если передан экземпляр WP_HTTP_Response, функция возвращает его без изменений.
• Во всех остальных случаях функция создает новый объект WP_REST_Response на основе переданных данных и возвращает этот объект.

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

Рассмотрим пример использования функции rest_ensure_response() в кастомном REST API эндпоинте.

1. Зарегистрируем новый эндпоинт, используя функцию register_rest_route().
2. В обработчике эндпоинта используем rest_ensure_response() для приведения данных к объекту ответа REST API.

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

add_action('rest_api_init', function() {
    register_rest_route('myplugin/v1', '/data', array(
        'methods' => 'GET',
        'callback' => 'myplugin_get_data',
    ));
});

function myplugin_get_data() {
    // Пример данных, которые мы хотим вернуть
    $data = array(
        'name' => 'John Doe',
        'email' => '[email protected]',
    );

    // Приведение данных к объекту ответа REST API
    return rest_ensure_response( $data );
}

Мы используем хук rest_api_init для регистрации нового маршрута /myplugin/v1/data. Этот маршрут будет доступен по методу GET и будет обрабатываться функцией myplugin_get_data.

В функции myplugin_get_data мы создаем массив данных $data, который хотим вернуть как ответ на запрос к нашему эндпоинту. Функция rest_ensure_response() преобразует массив $data в объект WP_REST_Response, который затем возвращается в качестве ответа.

Заключение

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