WP_REST_Response

Core class used to implement a REST response object.

Defined (1)

The class is defined in the following location(s).

/wp-includes/rest-api/class-wp-rest-response.php  
  1. class WP_REST_Response extends WP_HTTP_Response { 
  2.  
  3. /** 
  4. * Links related to the response. 
  5. * @since 4.4.0 
  6. * @access protected 
  7. * @var array 
  8. */ 
  9. protected $links = array(); 
  10.  
  11. /** 
  12. * The route that was to create the response. 
  13. * @since 4.4.0 
  14. * @access protected 
  15. * @var string 
  16. */ 
  17. protected $matched_route = ''; 
  18.  
  19. /** 
  20. * The handler that was used to create the response. 
  21. * @since 4.4.0 
  22. * @access protected 
  23. * @var null|array 
  24. */ 
  25. protected $matched_handler = null; 
  26.  
  27. /** 
  28. * Adds a link to the response. 
  29. * @internal The $rel parameter is first, as this looks nicer when sending multiple. 
  30. * @since 4.4.0 
  31. * @access public 
  32. * @link https://tools.ietf.org/html/rfc5988 
  33. * @link https://www.iana.org/assignments/link-relations/link-relations.xml 
  34. * @param string $rel Link relation. Either an IANA registered type,  
  35. * or an absolute URL. 
  36. * @param string $href Target URI for the link. 
  37. * @param array $attributes Optional. Link parameters to send along with the URL. Default empty array. 
  38. */ 
  39. public function add_link( $rel, $href, $attributes = array() ) { 
  40. if ( empty( $this->links[ $rel ] ) ) { 
  41. $this->links[ $rel ] = array(); 
  42.  
  43. if ( isset( $attributes['href'] ) ) { 
  44. // Remove the href attribute, as it's used for the main URL. 
  45. unset( $attributes['href'] ); 
  46.  
  47. $this->links[ $rel ][] = array( 
  48. 'href' => $href,  
  49. 'attributes' => $attributes,  
  50. ); 
  51.  
  52. /** 
  53. * Removes a link from the response. 
  54. * @since 4.4.0 
  55. * @access public 
  56. * @param string $rel Link relation. Either an IANA registered type, or an absolute URL. 
  57. * @param string $href Optional. Only remove links for the relation matching the given href. 
  58. * Default null. 
  59. */ 
  60. public function remove_link( $rel, $href = null ) { 
  61. if ( ! isset( $this->links[ $rel ] ) ) { 
  62. return; 
  63.  
  64. if ( $href ) { 
  65. $this->links[ $rel ] = wp_list_filter( $this->links[ $rel ], array( 'href' => $href ), 'NOT' ); 
  66. } else { 
  67. $this->links[ $rel ] = array(); 
  68.  
  69. if ( ! $this->links[ $rel ] ) { 
  70. unset( $this->links[ $rel ] ); 
  71.  
  72. /** 
  73. * Adds multiple links to the response. 
  74. * Link data should be an associative array with link relation as the key. 
  75. * The value can either be an associative array of link attributes 
  76. * (including `href` with the URL for the response), or a list of these 
  77. * associative arrays. 
  78. * @since 4.4.0 
  79. * @access public 
  80. * @param array $links Map of link relation to list of links. 
  81. */ 
  82. public function add_links( $links ) { 
  83. foreach ( $links as $rel => $set ) { 
  84. // If it's a single link, wrap with an array for consistent handling. 
  85. if ( isset( $set['href'] ) ) { 
  86. $set = array( $set ); 
  87.  
  88. foreach ( $set as $attributes ) { 
  89. $this->add_link( $rel, $attributes['href'], $attributes ); 
  90.  
  91. /** 
  92. * Retrieves links for the response. 
  93. * @since 4.4.0 
  94. * @access public 
  95. * @return array List of links. 
  96. */ 
  97. public function get_links() { 
  98. return $this->links; 
  99.  
  100. /** 
  101. * Sets a single link header. 
  102. * @internal The $rel parameter is first, as this looks nicer when sending multiple. 
  103. * @since 4.4.0 
  104. * @access public 
  105. * @link https://tools.ietf.org/html/rfc5988 
  106. * @link https://www.iana.org/assignments/link-relations/link-relations.xml 
  107. * @param string $rel Link relation. Either an IANA registered type, or an absolute URL. 
  108. * @param string $link Target IRI for the link. 
  109. * @param array $other Optional. Other parameters to send, as an assocative array. 
  110. * Default empty array. 
  111. */ 
  112. public function link_header( $rel, $link, $other = array() ) { 
  113. $header = '<' . $link . '>; rel="' . $rel . '"'; 
  114.  
  115. foreach ( $other as $key => $value ) { 
  116. if ( 'title' === $key ) { 
  117. $value = '"' . $value . '"'; 
  118. $header .= '; ' . $key . '=' . $value; 
  119. $this->header( 'Link', $header, false ); 
  120.  
  121. /** 
  122. * Retrieves the route that was used. 
  123. * @since 4.4.0 
  124. * @access public 
  125. * @return string The matched route. 
  126. */ 
  127. public function get_matched_route() { 
  128. return $this->matched_route; 
  129.  
  130. /** 
  131. * Sets the route (regex for path) that caused the response. 
  132. * @since 4.4.0 
  133. * @access public 
  134. * @param string $route Route name. 
  135. */ 
  136. public function set_matched_route( $route ) { 
  137. $this->matched_route = $route; 
  138.  
  139. /** 
  140. * Retrieves the handler that was used to generate the response. 
  141. * @since 4.4.0 
  142. * @access public 
  143. * @return null|array The handler that was used to create the response. 
  144. */ 
  145. public function get_matched_handler() { 
  146. return $this->matched_handler; 
  147.  
  148. /** 
  149. * Retrieves the handler that was responsible for generating the response. 
  150. * @since 4.4.0 
  151. * @access public 
  152. * @param array $handler The matched handler. 
  153. */ 
  154. public function set_matched_handler( $handler ) { 
  155. $this->matched_handler = $handler; 
  156.  
  157. /** 
  158. * Checks if the response is an error, i.e. >= 400 response code. 
  159. * @since 4.4.0 
  160. * @access public 
  161. * @return bool Whether the response is an error. 
  162. */ 
  163. public function is_error() { 
  164. return $this->get_status() >= 400; 
  165.  
  166. /** 
  167. * Retrieves a WP_Error object from the response. 
  168. * @since 4.4.0 
  169. * @access public 
  170. * @return WP_Error|null WP_Error or null on not an errored response. 
  171. */ 
  172. public function as_error() { 
  173. if ( ! $this->is_error() ) { 
  174. return null; 
  175.  
  176. $error = new WP_Error; 
  177.  
  178. if ( is_array( $this->get_data() ) ) { 
  179. $data = $this->get_data(); 
  180. $error->add( $data['code'], $data['message'], $data['data'] ); 
  181. if ( ! empty( $data['additional_errors'] ) ) { 
  182. foreach( $data['additional_errors'] as $err ) { 
  183. $error->add( $err['code'], $err['message'], $err['data'] ); 
  184. } else { 
  185. $error->add( $this->get_status(), '', array( 'status' => $this->get_status() ) ); 
  186.  
  187. return $error; 
  188.  
  189. /** 
  190. * Retrieves the CURIEs (compact URIs) used for relations. 
  191. * @since 4.5.0 
  192. * @access public 
  193. * @return array Compact URIs. 
  194. */ 
  195. public function get_curies() { 
  196. $curies = array( 
  197. array( 
  198. 'name' => 'wp',  
  199. 'href' => 'https://api.w.org/{rel}',  
  200. 'templated' => true,  
  201. ),  
  202. ); 
  203.  
  204. /** 
  205. * Filters extra CURIEs available on API responses. 
  206. * CURIEs allow a shortened version of URI relations. This allows a more 
  207. * usable form for custom relations than using the full URI. These work 
  208. * similarly to how XML namespaces work. 
  209. * Registered CURIES need to specify a name and URI template. This will 
  210. * automatically transform URI relations into their shortened version. 
  211. * The shortened relation follows the format `{name}:{rel}`. `{rel}` in 
  212. * the URI template will be replaced with the `{rel}` part of the 
  213. * shortened relation. 
  214. * For example, a CURIE with name `example` and URI template 
  215. * `http://w.org/{rel}` would transform a `http://w.org/term` relation 
  216. * into `example:term`. 
  217. * Well-behaved clients should expand and normalise these back to their 
  218. * full URI relation, however some naive clients may not resolve these 
  219. * correctly, so adding new CURIEs may break backward compatibility. 
  220. * @since 4.5.0 
  221. * @param array $additional Additional CURIEs to register with the API. 
  222. */ 
  223. $additional = apply_filters( 'rest_response_link_curies', array() ); 
  224. return array_merge( $curies, $additional );