rest_ensure_response()

💡 云策文档标注

概述

rest_ensure_response() 是 WordPress REST API 中的一个核心函数，用于确保响应对象的一致性。它检查输入参数并返回适当的 WP_REST_Response 或 WP_Error 实例，简化了 REST 响应处理。

关键要点

函数接受一个参数 $response，类型可以是 WP_REST_Response、WP_Error、WP_HTTP_Response 或任意混合类型，用于检查并确保响应对象。
返回类型为 WP_REST_Response 或 WP_Error：如果输入是 WP_Error，则直接返回；如果是 WP_REST_Response 实例，则返回原实例；否则创建新的 WP_REST_Response 实例。
该函数在 WordPress 4.4.0 版本中引入，广泛用于 REST API 控制器中，如 prepare_item_for_response 方法，以确保响应格式统一。

代码示例

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 );
}

注意事项

开发者在使用此函数时，应检查返回值是否为 WP_Error，以正确处理错误响应。此外，虽然 WP_HTTP_Response 是 WP_REST_Response 的基类，但可能缺少某些必要方法，因此函数会将其转换为 WP_REST_Response 实例。

📄 原文内容

Ensures a REST response is a response object (for consistency).

Description

This implements WP_REST_Response, allowing usage of set_status/header/etc without needing to double-check the object. Will also allow WP_Error to indicate error responses, so users should immediately check for this value.

Parameters

$responseWP_REST_Response|WP_Error|WP_HTTP_Response|mixedrequired: Response to check.

Return

WP_REST_Response|WP_Error If response generated an error, WP_Error, if response is already an instance, WP_REST_Response, otherwise returns a new WP_REST_Response instance.

Source

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 );
}

View all references View on Trac View on GitHub

Uses	Description
is_wp_error()`wp-includes/load.php`	Checks whether the given variable is a WordPress Error.

Used by	Description
WP_REST_Abilities_V1_Categories_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php`	Retrieves all ability categories.
WP_REST_Abilities_V1_Categories_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php`	Retrieves a specific ability category.
WP_REST_Abilities_V1_Categories_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-categories-controller.php`	Prepares an ability category for response.
WP_REST_Abilities_V1_Run_Controller::execute_ability()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php`	Executes an ability.
WP_REST_Abilities_V1_List_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php`	Retrieves all abilities.
WP_REST_Abilities_V1_List_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php`	Retrieves a specific ability.
WP_REST_Abilities_V1_List_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-list-controller.php`	Prepares an ability for response.
WP_REST_Font_Faces_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-font-faces-controller.php`	Prepares a single font face output for response.
WP_REST_Font_Families_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-font-families-controller.php`	Prepares a single font family output for response.
WP_REST_Font_Collections_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-font-collections-controller.php`	Prepare a single collection output for response.
WP_REST_Font_Collections_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-font-collections-controller.php`	Gets the font collections available.
WP_REST_Navigation_Fallback_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-navigation-fallback-controller.php`	Gets the most appropriate fallback Navigation Menu.
WP_REST_Navigation_Fallback_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-navigation-fallback-controller.php`	Matches the post data to the schema we want.
WP_REST_Global_Styles_Revisions_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-global-styles-revisions-controller.php`	Returns paginated revisions of the given global styles config custom post type.
WP_REST_Global_Styles_Revisions_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-global-styles-revisions-controller.php`	Prepares the revision for the REST response.
WP_REST_Templates_Controller::get_template_fallback()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Returns the fallback template for the given slug.
WP_REST_Block_Patterns_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php`	Retrieves all block patterns.
WP_REST_Block_Patterns_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php`	Prepare a raw block pattern before it gets output in a REST API response.
WP_REST_Global_Styles_Controller::get_theme_items()`wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php`	Returns the given theme global styles variations.
WP_REST_Block_Pattern_Categories_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-block-pattern-categories-controller.php`	Retrieves all block pattern categories.
WP_REST_Block_Pattern_Categories_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-block-pattern-categories-controller.php`	Prepare a raw block pattern category before it gets output in a REST API response.
WP_REST_Menu_Items_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php`	Prepares a single nav menu item output for response.
WP_REST_Global_Styles_Controller::get_theme_item()`wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php`	Returns the given theme global styles config.
WP_REST_Menu_Items_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php`	Creates a single nav menu item.
WP_REST_Menu_Items_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php`	Updates a single nav menu item.
WP_REST_Global_Styles_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php`	Prepare a global styles config output for response.
WP_REST_URL_Details_Controller::parse_url_details()`wp-includes/rest-api/endpoints/class-wp-rest-url-details-controller.php`	Retrieves the contents of the title tag from the HTML response.
WP_REST_Menus_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php`	Prepares a single term output for response.
WP_REST_Menus_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php`	Creates a single term in a taxonomy.
WP_REST_Menus_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php`	Updates a single term from a taxonomy.
WP_REST_Menu_Locations_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-menu-locations-controller.php`	Retrieves all menu locations, depending on user context.
WP_REST_Menu_Locations_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-menu-locations-controller.php`	Retrieves a specific menu location.
WP_REST_Menu_Locations_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-menu-locations-controller.php`	Prepares a menu location object for serialization.
WP_REST_Widgets_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php`	Prepares the widget for the REST response.
WP_REST_Sidebars_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php`	Retrieves the list of sidebars (active or inactive).
WP_REST_Sidebars_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php`	Prepares a single sidebar output for response.
WP_REST_Templates_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Prepare a single template output for response
WP_REST_Templates_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Returns a list of templates.
WP_REST_Templates_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Updates a single template.
WP_REST_Templates_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php`	Creates a single template.
WP_REST_Widget_Types_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	Retrieves a single widget type from the collection.
WP_REST_Widget_Types_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	Prepares a widget type object for serialization.
WP_REST_Widget_Types_Controller::encode_form_data()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	An RPC-style endpoint which can be used by clients to turn user input in a widget admin form into an encoded instance object.
WP_REST_Widget_Types_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-widget-types-controller.php`	Retrieves the list of all widget types.
WP_REST_Themes_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php`	Retrieves a single theme.
WP_REST_Server::serve_batch_request_v1()`wp-includes/rest-api/class-wp-rest-server.php`	Serves the batch/v1 request.
WP_REST_Server::respond_to_request()`wp-includes/rest-api/class-wp-rest-server.php`	Dispatches the request to the callback handler.
WP_REST_Block_Directory_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php`	Search and retrieve blocks metadata
WP_REST_Block_Types_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php`	Retrieves a specific block type.
WP_REST_Block_Types_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php`	Prepares a block type object for serialization.
WP_REST_Block_Types_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php`	Retrieves all post block types, depending on user context.
WP_REST_Search_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php`	Retrieves a collection of search results.
WP_REST_Search_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php`	Prepares a single search result for response.
WP_REST_Themes_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php`	Retrieves a collection of themes.
WP_REST_Themes_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-themes-controller.php`	Prepares a single theme output for response.
WP_REST_Autosaves_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php`	Creates, updates or deletes an autosave revision.
WP_REST_Autosaves_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php`	Gets a collection of autosaves using wp_get_post_autosave.
WP_REST_Block_Renderer_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php`	Returns block output from block’s registered render_callback.
rest_preload_api_request()`wp-includes/rest-api.php`	Append result of internal request to REST API for purpose of preloading data to be attached to a page.
WP_REST_Users_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Prepares a single user output for response.
WP_REST_Users_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Retrieves a single user.
WP_REST_Users_Controller::get_current_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Retrieves the current user.
WP_REST_Users_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Creates a single user.
WP_REST_Users_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Updates a single user.
WP_REST_Users_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php`	Retrieves all users.
WP_REST_Revisions_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php`	Retrieves one revision from the collection.
WP_REST_Revisions_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php`	Prepares the revision for the REST response.
WP_REST_Revisions_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php`	Gets a collection of revisions.
WP_REST_Attachments_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Creates a single attachment.
WP_REST_Attachments_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Updates a single attachment.
WP_REST_Attachments_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Prepares a single attachment output for response.
WP_REST_Post_Statuses_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php`	Retrieves all post statuses, depending on user context.
WP_REST_Post_Statuses_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php`	Retrieves a specific post status.
WP_REST_Post_Statuses_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php`	Prepares a post status object for serialization.
WP_REST_Terms_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php`	Prepares a single term output for response.
WP_REST_Terms_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php`	Gets a single term from a taxonomy.
WP_REST_Terms_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php`	Creates a single term in a taxonomy.
WP_REST_Terms_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php`	Updates a single term from a taxonomy.
WP_REST_Terms_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php`	Retrieves terms associated with a taxonomy.
WP_REST_Posts_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Prepares a single post output for response.
WP_REST_Posts_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Creates a single post.
WP_REST_Posts_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Updates a single post.
WP_REST_Posts_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Retrieves a single post.
WP_REST_Posts_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Retrieves a collection of posts.
WP_REST_Taxonomies_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php`	Retrieves a specific taxonomy.
WP_REST_Taxonomies_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php`	Prepares a taxonomy object for serialization.
WP_REST_Taxonomies_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php`	Retrieves all public taxonomies.
WP_REST_Post_Types_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php`	Retrieves all public post types.
WP_REST_Post_Types_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php`	Retrieves a specific post type.
WP_REST_Post_Types_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-post-types-controller.php`	Prepares a post type object for serialization.
WP_REST_Comments_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php`	Prepares a single comment output for response.
WP_REST_Comments_Controller::update_item()`wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php`	Updates a comment.
WP_REST_Comments_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php`	Retrieves a comment.
WP_REST_Comments_Controller::create_item()`wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php`	Creates a comment.
WP_REST_Comments_Controller::get_items()`wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php`	Retrieves a list of comment items.
WP_REST_Server::dispatch()`wp-includes/rest-api/class-wp-rest-server.php`	Matches the request to a callback and call it.
WP_REST_Server::get_namespace_index()`wp-includes/rest-api/class-wp-rest-server.php`	Retrieves the index for a namespace.
WP_REST_Server::envelope_response()`wp-includes/rest-api/class-wp-rest-server.php`	Wraps the response in an envelope.
WP_REST_Server::serve_request()`wp-includes/rest-api/class-wp-rest-server.php`	Handles serving a REST API request.
WP_REST_Server::embed_links()`wp-includes/rest-api/class-wp-rest-server.php`	Embeds the links from the data into the request.

Show 95 more Show less

Changelog

Version	Description
4.4.0	Introduced.

云策 WordPress 开发者社区

函数文档

rest_ensure_response()

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Changelog

函数文档

概述

关键要点

代码示例

注意事项

Description

Parameters

Return

Source

Related

Changelog