290 lines
7.2 KiB
PHP
290 lines
7.2 KiB
PHP
<?php
|
|
/**
|
|
* REST API: WP_REST_Response class
|
|
*
|
|
* @package WordPress
|
|
* @subpackage REST_API
|
|
* @since 4.4.0
|
|
*/
|
|
|
|
/**
|
|
* Core class used to implement a REST response object.
|
|
*
|
|
* @since 4.4.0
|
|
*
|
|
* @see WP_HTTP_Response
|
|
*/
|
|
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 assocative 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;
|
|
}
|
|
|
|
/**
|
|
* Retrieves 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 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
|
|
* `http://w.org/{rel}` would transform a `http://w.org/term` relation
|
|
* into `example:term`.
|
|
*
|
|
* Well-behaved clients should expand and normalise 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 API.
|
|
*/
|
|
$additional = apply_filters( 'rest_response_link_curies', array() );
|
|
return array_merge( $curies, $additional );
|
|
}
|
|
}
|