diff options
Diffstat (limited to '')
| -rw-r--r-- | wp-includes/rest-api/class-wp-rest-response.php | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/wp-includes/rest-api/class-wp-rest-response.php b/wp-includes/rest-api/class-wp-rest-response.php new file mode 100644 index 0000000..c6ea11b --- /dev/null +++ b/wp-includes/rest-api/class-wp-rest-response.php @@ -0,0 +1,293 @@ +<?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 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 + * `http://w.org/{rel}` would transform a `http://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 ); + } +} |