云策 WordPress 开发者社区

类文档

WP_REST_Response

查看官方原文 ↗
💡 云策文档标注

概述

WP_REST_Response 是 WordPress 中用于实现 REST 响应对象的核心类，继承自 WP_HTTP_Response。它提供了处理响应数据、链接、路由和错误的方法，适用于 REST API 开发。

关键要点

  • 继承自 WP_HTTP_Response，用于构建和管理 REST API 响应。
  • 支持添加、移除和获取链接（links），包括单个和批量操作，遵循 RFC 5988 和 IANA 标准。
  • 提供方法处理匹配的路由（matched_route）和处理器（matched_handler），便于调试和跟踪响应来源。
  • 包含错误检查方法（is_error）和转换方法（as_error），可将错误响应转换为 WP_Error 对象。
  • 支持 CURIEs（紧凑 URI）用于缩短关系 URI，可通过过滤器扩展。
  • 可用于创建重定向响应或自定义 JSON 响应，增强 REST API 的灵活性和用户体验。

代码示例

// 示例：创建重定向响应
return new WP_REST_Response(
    null, // 无响应体内容
    303, // HTTP 303 See Other
    array(
        'Location' => site_url('/thank-you/'), // 重定向到成功页面
    )
);

注意事项

  • 使用 WP_REST_Response 而非 WP_Error 处理远程请求响应，以保持一致性。
  • 添加新 CURIEs 可能破坏向后兼容性，需谨慎使用过滤器。
  • 链接操作时需注意 href 属性的处理，避免重复设置。
📄 原文内容

Core class used to implement a REST response object.

Description

See also

Methods

Name Description
WP_REST_Response::add_link Adds a link to the response.
WP_REST_Response::add_links Adds multiple links to the response.
WP_REST_Response::as_error Retrieves a WP_Error object from the response.
WP_REST_Response::get_curies Retrieves the CURIEs (compact URIs) used for relations.
WP_REST_Response::get_links Retrieves links for the response.
WP_REST_Response::get_matched_handler Retrieves the handler that was used to generate the response.
WP_REST_Response::get_matched_route Retrieves the route that was used.
WP_REST_Response::is_error Checks if the response is an error, i.e. >= 400 response code.
WP_REST_Response::link_header Sets a single link header.
WP_REST_Response::remove_link Removes a link from the response.
WP_REST_Response::set_matched_handler Sets the handler that was responsible for generating the response.
WP_REST_Response::set_matched_route Sets the route (regex for path) that caused the response.

Source

class WP_REST_Response extends WP_HTTP_Response {

	/**
	 * Links related to the response.
	 *
	 * @since 4.4.0
	 * @var array
	 */
	protected $links = array();

	/**
	 * The route that was to create the response.
	 *
	 * @since 4.4.0
	 * @var string
	 */
	protected $matched_route = '';

	/**
	 * The handler that was used to create the response.
	 *
	 * @since 4.4.0
	 * @var null|array
	 */
	protected $matched_handler = null;

	/**
	 * Adds a link to the response.
	 *
	 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.}
	 *
	 * @since 4.4.0
	 *
	 * @link https://tools.ietf.org/html/rfc5988
	 * @link https://www.iana.org/assignments/link-relations/link-relations.xml
	 *
	 * @param string $rel        Link relation. Either an IANA registered type,
	 *                           or an absolute URL.
	 * @param string $href       Target URI for the link.
	 * @param array  $attributes Optional. Link parameters to send along with the URL. Default empty array.
	 */
	public function add_link( $rel, $href, $attributes = array() ) {
		if ( empty( $this->links[ $rel ] ) ) {
			$this->links[ $rel ] = array();
		}

		if ( isset( $attributes['href'] ) ) {
			// Remove the href attribute, as it's used for the main URL.
			unset( $attributes['href'] );
		}

		$this->links[ $rel ][] = array(
			'href'       => $href,
			'attributes' => $attributes,
		);
	}

	/**
	 * Removes a link from the response.
	 *
	 * @since 4.4.0
	 *
	 * @param string      $rel  Link relation. Either an IANA registered type, or an absolute URL.
	 * @param string|null $href Optional. Only remove links for the relation matching the given href.
	 *                          Default null.
	 */
	public function remove_link( $rel, $href = null ) {
		if ( ! isset( $this->links[ $rel ] ) ) {
			return;
		}

		if ( $href ) {
			$this->links[ $rel ] = wp_list_filter( $this->links[ $rel ], array( 'href' => $href ), 'NOT' );
		} else {
			$this->links[ $rel ] = array();
		}

		if ( ! $this->links[ $rel ] ) {
			unset( $this->links[ $rel ] );
		}
	}

	/**
	 * Adds multiple links to the response.
	 *
	 * Link data should be an associative array with link relation as the key.
	 * The value can either be an associative array of link attributes
	 * (including `href` with the URL for the response), or a list of these
	 * associative arrays.
	 *
	 * @since 4.4.0
	 *
	 * @param array $links Map of link relation to list of links.
	 */
	public function add_links( $links ) {
		foreach ( $links as $rel => $set ) {
			// If it's a single link, wrap with an array for consistent handling.
			if ( isset( $set['href'] ) ) {
				$set = array( $set );
			}

			foreach ( $set as $attributes ) {
				$this->add_link( $rel, $attributes['href'], $attributes );
			}
		}
	}

	/**
	 * Retrieves links for the response.
	 *
	 * @since 4.4.0
	 *
	 * @return array List of links.
	 */
	public function get_links() {
		return $this->links;
	}

	/**
	 * Sets a single link header.
	 *
	 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.}
	 *
	 * @since 4.4.0
	 *
	 * @link https://tools.ietf.org/html/rfc5988
	 * @link https://www.iana.org/assignments/link-relations/link-relations.xml
	 *
	 * @param string $rel   Link relation. Either an IANA registered type, or an absolute URL.
	 * @param string $link  Target IRI for the link.
	 * @param array  $other Optional. Other parameters to send, as an associative array.
	 *                      Default empty array.
	 */
	public function link_header( $rel, $link, $other = array() ) {
		$header = '<' . $link . '>; rel="' . $rel . '"';

		foreach ( $other as $key => $value ) {
			if ( 'title' === $key ) {
				$value = '"' . $value . '"';
			}

			$header .= '; ' . $key . '=' . $value;
		}
		$this->header( 'Link', $header, false );
	}

	/**
	 * Retrieves the route that was used.
	 *
	 * @since 4.4.0
	 *
	 * @return string The matched route.
	 */
	public function get_matched_route() {
		return $this->matched_route;
	}

	/**
	 * Sets the route (regex for path) that caused the response.
	 *
	 * @since 4.4.0
	 *
	 * @param string $route Route name.
	 */
	public function set_matched_route( $route ) {
		$this->matched_route = $route;
	}

	/**
	 * Retrieves the handler that was used to generate the response.
	 *
	 * @since 4.4.0
	 *
	 * @return null|array The handler that was used to create the response.
	 */
	public function get_matched_handler() {
		return $this->matched_handler;
	}

	/**
	 * Sets the handler that was responsible for generating the response.
	 *
	 * @since 4.4.0
	 *
	 * @param array $handler The matched handler.
	 */
	public function set_matched_handler( $handler ) {
		$this->matched_handler = $handler;
	}

	/**
	 * Checks if the response is an error, i.e. >= 400 response code.
	 *
	 * @since 4.4.0
	 *
	 * @return bool Whether the response is an error.
	 */
	public function is_error() {
		return $this->get_status() >= 400;
	}

	/**
	 * Retrieves a WP_Error object from the response.
	 *
	 * @since 4.4.0
	 *
	 * @return WP_Error|null WP_Error or null on not an errored response.
	 */
	public function as_error() {
		if ( ! $this->is_error() ) {
			return null;
		}

		$error = new WP_Error();

		if ( is_array( $this->get_data() ) ) {
			$data = $this->get_data();
			$error->add( $data['code'], $data['message'], $data['data'] );

			if ( ! empty( $data['additional_errors'] ) ) {
				foreach ( $data['additional_errors'] as $err ) {
					$error->add( $err['code'], $err['message'], $err['data'] );
				}
			}
		} else {
			$error->add( $this->get_status(), '', array( 'status' => $this->get_status() ) );
		}

		return $error;
	}

	/**
	 * Retrieves the CURIEs (compact URIs) used for relations.
	 *
	 * @since 4.5.0
	 *
	 * @return array Compact URIs.
	 */
	public function get_curies() {
		$curies = array(
			array(
				'name'      => 'wp',
				'href'      => 'https://api.w.org/{rel}',
				'templated' => true,
			),
		);

		/**
		 * Filters extra CURIEs available on REST API responses.
		 *
		 * CURIEs allow a shortened version of URI relations. This allows a more
		 * usable form for custom relations than using the full URI. These work
		 * similarly to how XML namespaces work.
		 *
		 * Registered CURIES need to specify a name and URI template. This will
		 * automatically transform URI relations into their shortened version.
		 * The shortened relation follows the format `{name}:{rel}`. `{rel}` in
		 * the URI template will be replaced with the `{rel}` part of the
		 * shortened relation.
		 *
		 * For example, a CURIE with name `example` and URI template
		 * `https://w.org/{rel}` would transform a `https://w.org/term` relation
		 * into `example:term`.
		 *
		 * Well-behaved clients should expand and normalize these back to their
		 * full URI relation, however some naive clients may not resolve these
		 * correctly, so adding new CURIEs may break backward compatibility.
		 *
		 * @since 4.5.0
		 *
		 * @param array $additional Additional CURIEs to register with the REST API.
		 */
		$additional = apply_filters( 'rest_response_link_curies', array() );

		return array_merge( $curies, $additional );
	}
}

View all references View on Trac View on GitHub

Uses Description
WP_HTTP_Responsewp-includes/class-wp-http-response.php

Core class used to prepare HTTP responses.

Changelog

Version Description
4.4.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Khoi Pro


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    When you call to a remote url, it’s better to response using this class than WP_Error().

    function load_request() {
  $token = '<your_api_key>';
  $url = '<your_api_url>';
  $args = array(
    'headers' => array(
      'Authentication' => "Basic $token"
    )
  );

  // Send remote request
  $request = wp_remote_get($url, $args);

  // Retrieve information
  $response_code = wp_remote_retrieve_response_code($request);
  $response_message = wp_remote_retrieve_response_message($request);
  $response_body = wp_remote_retrieve_body($request);

  if (!is_wp_error($request) ) {
    return new WP_REST_Response(
      array(
        'status' => $response_code,
        'response' => $response_message,
        'body_response' => $response_body
      );
    );
  } else {
    return new WP_Error($response_code, $response_message, $response_body);
  }
}

  2. Skip to note 4 content


    Michelle Blanchette


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    You can create a redirect response like so:

    return new WP_REST_Response(
	null, // No response body content.
	303, // HTTP 303 See Other.
	array(
		'Location' => site_url( '/thank-you/' ), // Redirect to success page.
	)
);

    This HTTP response has no body content, status code HTTP 303 See Other, and the Location header to redirect the user to a confirmation page.

    This is especially useful when adding custom WordPress REST API endpoints which do some processing. Since the WordPress REST API always returns JSON, you can instead redirect the user to a success or error page after processing completes to view the result in HTML. This provides an accessible user experience without the need for implementing AJAX request handling in JavaScript to use the WordPress REST API.

    Then you can use REST URLs as simple links to do some processing:

    // Get the REST API endpoint URL to subscribe the user to email notifications.
$rest_endpoint_url = rest_url( 'my-plugin/v1/subscribe' );

// Display the link with WordPress REST API user authentication nonce.
// Redirects the user to a success or error page after processing the request.
printf(
	'<a href="%s" rel="nofollow ugc">Enable Notifications</a>',
	wp_nonce_url( $rest_endpoint_url, 'wp_rest', '_wpnonce' )
);