rest_ensure_response() │ WP 4.4.0

Проверяет и, если надо, преобразует переданные данные в объект класса WP_HTTP_Response.

Используется для стабильной работы кода при создании ответов в REST API.

Функция проверят переданные данные и если нужно превращает их в объект WP_REST_Response. Далее, этот объект позволяет использовать методы set_status(), set_headers(), set_data() и другие.

Если передан объект WP_Error или экземпляр класса WP_HTTP_Response, то они будут возвращены как есть без изменений.

Через эту функцию WP автоматически пропускает любые данные, которые возвращаются как ответ в REST API. Например когда коллбек функция register_rest_route() возвращает строку, эта строка в итоге пропускается через эту функцию.

Работает на основе: WP_REST_Response()

Хуков нет.

Возвращает

WP_REST_Response|WP_Error.

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

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

rest_ensure_response( $response );
$response(WP_Error/WP_HTTP_Response/разное) (обязательный)
Данные ответа, которые нужно проверить и возможно превратить в объект WP_HTTP_Response.

Примеры

0

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

В WordPress для этой цели есть дефолтные методы, но давайте для примера создадим свой простой вариант:

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

// Обрабатывает запрос
function my_awesome_func( WP_REST_Request $request ) {

	$posts = get_posts( array(
		'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( [
		//'CONTENT_TYPE'   => 'application/x-www-form-urlencoded',
		//'CONTENT_LENGTH' => 105,
		'X_REAL_IP'      => '54.15.124.126',
	] );
	//$this->set_data( $data );

	return $response;
}

Список изменений

С версии 4.4.0 Введена.

Код rest_ensure_response() WP 6.8.3

wp-includes/rest-api.php 
function rest_ensure_response( $response ) {
	if ( is_wp_error( $response ) ) {
		return $response;
	}

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

	/*
	 * While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide
	 * all the required methods used in 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 API