class WP_REST_Response {}

Core class used to implement a REST response object.

Description

See also

Methods

NameDescription
WP_REST_Response::add_linkAdds a link to the response.
WP_REST_Response::add_linksAdds multiple links to the response.
WP_REST_Response::as_errorRetrieves a WP_Error object from the response.
WP_REST_Response::get_curiesRetrieves the CURIEs (compact URIs) used for relations.
WP_REST_Response::get_linksRetrieves links for the response.
WP_REST_Response::get_matched_handlerRetrieves the handler that was used to generate the response.
WP_REST_Response::get_matched_routeRetrieves the route that was used.
WP_REST_Response::is_errorChecks if the response is an error, i.e. >= 400 response code.
WP_REST_Response::link_headerSets a single link header.
WP_REST_Response::remove_linkRemoves a link from the response.
WP_REST_Response::set_matched_handlerSets the handler that was responsible for generating the response.
WP_REST_Response::set_matched_routeSets 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 $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 );
	}
}

Changelog

VersionDescription
4.4.0Introduced.

User Contributed Notes

  1. Skip to note 3 content

    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

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

You must log in before being able to contribute a note or feedback.