Функция rest_ensure_response()

Введение

Функция rest_ensure_response() в WordPress гарантирует, что полученный ответ является объектом ответа (дляConsistency). Она обрабатывает объект WP_REST_Response и позволяет использовать методы, такие как set_status и set_header, без необходимости дважды проверять объект. Если происходит ошибка, то функция возвращает объект WP_Error, поэтому пользователи должны сразу проверять этот результат.

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

Функция может вернуть:

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

Использование

Чтобы использовать функцию, вам нужно передать ей ответ. Пример вызова:

rest_ensure_response( $response );

Параметры

• $response (WP_REST_Response|WP_Error|WP_HTTP_Response|mixed): Ответ, который необходимо проверить. Этот параметр является обязательным.

Примеры

Пример 1: Получение постов указанного автора

В WordPress есть встроенные методы для этого, но давайте создадим собственную простую версию в качестве примера:

// Регистрируем маршрут
add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/author/(?Pd+)', array(
        'methods'  => 'GET',
        'callback' => 'my_awesome_func',
    ) );
} );

// Обработка запроса
function my_awesome_func( WP_REST_Request $request ) {
    $posts = get_posts( [
        'author' => (int) $request['id'],
    ] );

    if ( empty( $posts ) ) {
        return new WP_Error('no_author_posts', 'Посты не найдены', array( 'status' => 404 ));
    }

    $response = rest_ensure_response( $posts );
    $response->set_status( 201 );
    $response->set_headers( [
        'X_REAL_IP' => '54.15.124.126',
    ] );

    return $response;
}

Изменения

Функция rest_ensure_response() была введена в версии 4.4.0.

Код функции

Вот внутренняя реализация функции:

function rest_ensure_response( $response ) {
    if ( is_wp_error( $response ) ) {
        return $response;
    }

    if ( $response instanceof WP_REST_Response ) {
        return $response;
    }

    /*
     * Хотя WP_HTTP_Response является базовым классом для WP_REST_Response, он не предоставляет
     * все необходимые методы, используемые в WP_REST_Server::dispatch().
     */
    if ( $response instanceof WP_HTTP_Response ) {
        return new WP_REST_Response(
            $response->get_data(),
            $response->get_status(),
            $response->get_headers()
        );
    }

    return new WP_REST_Response( $response );
}

Заключение

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