3 * REST API: WP_REST_Response class
11 * Core class used to implement a REST response object.
15 * @see WP_HTTP_Response
17 class WP_REST_Response extends WP_HTTP_Response {
20 * Links related to the response.
26 protected $links = array();
29 * The route that was to create the response.
35 protected $matched_route = '';
38 * The handler that was used to create the response.
44 protected $matched_handler = null;
47 * Adds a link to the response.
49 * @internal The $rel parameter is first, as this looks nicer when sending multiple.
54 * @link http://tools.ietf.org/html/rfc5988
55 * @link http://www.iana.org/assignments/link-relations/link-relations.xml
57 * @param string $rel Link relation. Either an IANA registered type,
59 * @param string $href Target URI for the link.
60 * @param array $attributes Optional. Link parameters to send along with the URL. Default empty array.
62 public function add_link( $rel, $href, $attributes = array() ) {
63 if ( empty( $this->links[ $rel ] ) ) {
64 $this->links[ $rel ] = array();
67 if ( isset( $attributes['href'] ) ) {
68 // Remove the href attribute, as it's used for the main URL.
69 unset( $attributes['href'] );
72 $this->links[ $rel ][] = array(
74 'attributes' => $attributes,
79 * Removes a link from the response.
84 * @param string $rel Link relation. Either an IANA registered type, or an absolute URL.
85 * @param string $href Optional. Only remove links for the relation matching the given href.
88 public function remove_link( $rel, $href = null ) {
89 if ( ! isset( $this->links[ $rel ] ) ) {
94 $this->links[ $rel ] = wp_list_filter( $this->links[ $rel ], array( 'href' => $href ), 'NOT' );
96 $this->links[ $rel ] = array();
99 if ( ! $this->links[ $rel ] ) {
100 unset( $this->links[ $rel ] );
105 * Adds multiple links to the response.
107 * Link data should be an associative array with link relation as the key.
108 * The value can either be an associative array of link attributes
109 * (including `href` with the URL for the response), or a list of these
110 * associative arrays.
115 * @param array $links Map of link relation to list of links.
117 public function add_links( $links ) {
118 foreach ( $links as $rel => $set ) {
119 // If it's a single link, wrap with an array for consistent handling.
120 if ( isset( $set['href'] ) ) {
121 $set = array( $set );
124 foreach ( $set as $attributes ) {
125 $this->add_link( $rel, $attributes['href'], $attributes );
131 * Retrieves links for the response.
136 * @return array List of links.
138 public function get_links() {
143 * Sets a single link header.
145 * @internal The $rel parameter is first, as this looks nicer when sending multiple.
150 * @link http://tools.ietf.org/html/rfc5988
151 * @link http://www.iana.org/assignments/link-relations/link-relations.xml
153 * @param string $rel Link relation. Either an IANA registered type, or an absolute URL.
154 * @param string $link Target IRI for the link.
155 * @param array $other Optional. Other parameters to send, as an assocative array.
156 * Default empty array.
158 public function link_header( $rel, $link, $other = array() ) {
159 $header = '<' . $link . '>; rel="' . $rel . '"';
161 foreach ( $other as $key => $value ) {
162 if ( 'title' === $key ) {
163 $value = '"' . $value . '"';
165 $header .= '; ' . $key . '=' . $value;
167 $this->header( 'Link', $header, false );
171 * Retrieves the route that was used.
176 * @return string The matched route.
178 public function get_matched_route() {
179 return $this->matched_route;
183 * Sets the route (regex for path) that caused the response.
188 * @param string $route Route name.
190 public function set_matched_route( $route ) {
191 $this->matched_route = $route;
195 * Retrieves the handler that was used to generate the response.
200 * @return null|array The handler that was used to create the response.
202 public function get_matched_handler() {
203 return $this->matched_handler;
207 * Retrieves the handler that was responsible for generating the response.
212 * @param array $handler The matched handler.
214 public function set_matched_handler( $handler ) {
215 $this->matched_handler = $handler;
219 * Checks if the response is an error, i.e. >= 400 response code.
224 * @return bool Whether the response is an error.
226 public function is_error() {
227 return $this->get_status() >= 400;
231 * Retrieves a WP_Error object from the response.
236 * @return WP_Error|null WP_Error or null on not an errored response.
238 public function as_error() {
239 if ( ! $this->is_error() ) {
243 $error = new WP_Error;
245 if ( is_array( $this->get_data() ) ) {
246 $data = $this->get_data();
247 $error->add( $data['code'], $data['message'], $data['data'] );
248 if ( ! empty( $data['additional_errors'] ) ) {
249 foreach( $data['additional_errors'] as $err ) {
250 $error->add( $err['code'], $err['message'], $err['data'] );
254 $error->add( $this->get_status(), '', array( 'status' => $this->get_status() ) );
261 * Retrieves the CURIEs (compact URIs) used for relations.
266 * @return array Compact URIs.
268 public function get_curies() {
272 'href' => 'https://api.w.org/{rel}',
278 * Filter extra CURIEs available on API responses.
280 * CURIEs allow a shortened version of URI relations. This allows a more
281 * usable form for custom relations than using the full URI. These work
282 * similarly to how XML namespaces work.
284 * Registered CURIES need to specify a name and URI template. This will
285 * automatically transform URI relations into their shortened version.
286 * The shortened relation follows the format `{name}:{rel}`. `{rel}` in
287 * the URI template will be replaced with the `{rel}` part of the
288 * shortened relation.
290 * For example, a CURIE with name `example` and URI template
291 * `http://w.org/{rel}` would transform a `http://w.org/term` relation
292 * into `example:term`.
294 * Well-behaved clients should expand and normalise these back to their
295 * full URI relation, however some naive clients may not resolve these
296 * correctly, so adding new CURIEs may break backwards compatibility.
300 * @param array $additional Additional CURIEs to register with the API.
302 $additional = apply_filters( 'rest_response_link_curies', array() );
303 return array_merge( $curies, $additional );