| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API: WP_REST_Response class 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 4.4.0 8 */ 9 10 /** 11 * Core class used to implement a REST response object. 12 * 13 * @since 4.4.0 14 * 15 * @see WP_HTTP_Response 16 * 17 * @phpstan-import-type Route_Handler from WP_REST_Server 18 * @phpstan-import-type Data_Processing from WP_REST_Server 19 * 20 * @phpstan-type Target_Hints array{ 21 * allow?: list<uppercase-string>, 22 * ...<lowercase-string, mixed> 23 * } 24 * @phpstan-type Link_Attributes array{ 25 * embeddable?: bool, 26 * targetHints?: Target_Hints, 27 * count?: int<0, max>, 28 * ...<string, mixed> 29 * } 30 * @phpstan-type Link array{ 31 * href: non-falsy-string, 32 * attributes: Link_Attributes, 33 * } 34 * @phpstan-type Link_Input array{ 35 * href: non-falsy-string, 36 * embeddable?: bool, 37 * targetHints?: array<string, mixed>, // Not narrowed like in Link_Attributes, since PHPStan merges this shape with its list form in add_links(). The merged attributes passed to add_link() there are only accepted while they include `mixed`; with the nested shape, the call would be an argument.type error even when `mixed` is not checked. 38 * count?: int<0, max>, // Declared rather than left to the unsealed keys, since that merge also drops them: an attribute not named here is rejected when a caller passes a precise shape. 39 * ...<string, mixed> 40 * } 41 * @phpstan-type Curie array{ 42 * name: string, // An empty name is a valid empty CURIE prefix, which WP_REST_Server::get_compact_response_links() handles consistently. 43 * href: non-falsy-string, 44 * templated?: bool, 45 * } 46 */ 47 class WP_REST_Response extends WP_HTTP_Response { 48 49 /** 50 * Links related to the response. 51 * 52 * @since 4.4.0 53 * @var array<string, array<string, mixed>[]> Map of link relation to list of links. 54 * @phpstan-var array<non-falsy-string, array<Link>> 55 */ 56 protected $links = array(); 57 58 /** 59 * The route that was to create the response. 60 * 61 * @since 4.4.0 62 * @var string 63 */ 64 protected $matched_route = ''; 65 66 /** 67 * The handler that was used to create the response. 68 * 69 * @since 4.4.0 70 * @var array<string, mixed>|null 71 * @phpstan-var Route_Handler|null 72 */ 73 protected $matched_handler = null; 74 75 /** 76 * Whether each data processing feature is on for the response. 77 * 78 * @since 7.2.0 79 * @var array<string, bool> Whether the `fields`, `embed` and `links` features are on. Every feature is on by default. 80 * @phpstan-var Data_Processing 81 */ 82 protected $data_processing = array( 83 'fields' => true, 84 'embed' => true, 85 'links' => true, 86 ); 87 88 /** 89 * Adds a link to the response. 90 * 91 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.} 92 * 93 * @since 4.4.0 94 * 95 * @link https://tools.ietf.org/html/rfc5988 96 * @link https://www.iana.org/assignments/link-relations/link-relations.xml 97 * 98 * @param string $rel Link relation. Either an IANA registered type, 99 * or an absolute URL. 100 * @param string $href Target URI for the link. 101 * @param array<string, mixed> $attributes Optional. Link parameters to send along with the URL. Default empty array. 102 * 103 * @phpstan-param non-falsy-string $rel 104 * @phpstan-param non-falsy-string $href 105 * @phpstan-param Link_Attributes $attributes 106 */ 107 public function add_link( $rel, $href, $attributes = array() ) { 108 if ( empty( $this->links[ $rel ] ) ) { 109 $this->links[ $rel ] = array(); 110 } 111 112 if ( isset( $attributes['href'] ) ) { 113 // Remove the href attribute, as it's used for the main URL. 114 unset( $attributes['href'] ); 115 } 116 117 $this->links[ $rel ][] = array( 118 'href' => $href, 119 'attributes' => $attributes, 120 ); 121 } 122 123 /** 124 * Removes a link from the response. 125 * 126 * @since 4.4.0 127 * 128 * @param string $rel Link relation. Either an IANA registered type, or an absolute URL. 129 * @param string|null $href Optional. Only remove links for the relation matching the given href. 130 * Default null. 131 * 132 * @phpstan-param non-falsy-string $rel 133 */ 134 public function remove_link( $rel, $href = null ) { 135 if ( ! isset( $this->links[ $rel ] ) ) { 136 return; 137 } 138 139 if ( $href ) { 140 $this->links[ $rel ] = wp_list_filter( $this->links[ $rel ], array( 'href' => $href ), 'NOT' ); 141 } else { 142 $this->links[ $rel ] = array(); 143 } 144 145 if ( ! $this->links[ $rel ] ) { 146 unset( $this->links[ $rel ] ); 147 } 148 } 149 150 /** 151 * Adds multiple links to the response. 152 * 153 * Link data should be an associative array with link relation as the key. 154 * The value can either be an associative array of link attributes 155 * (including `href` with the URL for the response), or a list of these 156 * associative arrays. 157 * 158 * @since 4.4.0 159 * 160 * @param array<string, array<mixed>> $links Map of link relation to a link's attributes, or to a list of these. 161 * 162 * @phpstan-param array<non-falsy-string, Link_Input|list<Link_Input>> $links 163 */ 164 public function add_links( $links ) { 165 foreach ( $links as $rel => $set ) { 166 // If it's a single link, wrap with an array for consistent handling. 167 if ( isset( $set['href'] ) ) { 168 $set = array( $set ); 169 } 170 171 foreach ( $set as $attributes ) { 172 $this->add_link( $rel, $attributes['href'], $attributes ); 173 } 174 } 175 } 176 177 /** 178 * Retrieves links for the response. 179 * 180 * @since 4.4.0 181 * 182 * @return array<string, array<string, mixed>[]> Map of link relation to list of links. 183 * 184 * @phpstan-return array<non-falsy-string, array<Link>> 185 */ 186 public function get_links() { 187 return $this->links; 188 } 189 190 /** 191 * Sets a single link header. 192 * 193 * {@internal The $rel parameter is first, as this looks nicer when sending multiple.} 194 * 195 * @since 4.4.0 196 * 197 * @link https://tools.ietf.org/html/rfc5988 198 * @link https://www.iana.org/assignments/link-relations/link-relations.xml 199 * 200 * @param string $rel Link relation. Either an IANA registered type, or an absolute URL. 201 * @param string $link Target IRI for the link. 202 * @param array<string, string> $other Optional. Other parameters to send, as an associative array. 203 * Default empty array. 204 * 205 * @phpstan-param non-falsy-string $rel 206 */ 207 public function link_header( $rel, $link, $other = array() ) { 208 $header = '<' . $link . '>; rel="' . $rel . '"'; 209 210 foreach ( $other as $key => $value ) { 211 if ( 'title' === $key ) { 212 $value = '"' . $value . '"'; 213 } 214 215 $header .= '; ' . $key . '=' . $value; 216 } 217 $this->header( 'Link', $header, false ); 218 } 219 220 /** 221 * Retrieves the route that was used. 222 * 223 * @since 4.4.0 224 * 225 * @return string The matched route. 226 */ 227 public function get_matched_route() { 228 return $this->matched_route; 229 } 230 231 /** 232 * Sets the route (regex for path) that caused the response. 233 * 234 * @since 4.4.0 235 * 236 * @param string $route Route name. 237 */ 238 public function set_matched_route( $route ) { 239 $this->matched_route = $route; 240 } 241 242 /** 243 * Retrieves the handler that was used to generate the response. 244 * 245 * @since 4.4.0 246 * 247 * @return array<string, mixed>|null The handler that was used to create the response. 248 * 249 * @phpstan-return Route_Handler|null 250 */ 251 public function get_matched_handler() { 252 return $this->matched_handler; 253 } 254 255 /** 256 * Sets the handler that was responsible for generating the response. 257 * 258 * @since 4.4.0 259 * 260 * @param array<string, mixed> $handler The matched handler. 261 * 262 * @phpstan-param Route_Handler $handler 263 */ 264 public function set_matched_handler( $handler ) { 265 $this->matched_handler = $handler; 266 } 267 268 /** 269 * Retrieves whether each data processing feature is on for the response. 270 * 271 * The server sets the settings of the matched route when it dispatches a request, for responses 272 * returned by the `rest_pre_dispatch` filter too. Every feature is on until then. 273 * 274 * @since 7.2.0 275 * 276 * @see WP_REST_Server::resolve_data_processing() 277 * 278 * @return array<string, bool> { 279 * Whether each data processing feature is on. 280 * 281 * @type bool $fields Whether the `_fields` parameter filters the response data. 282 * @type bool $embed Whether the `_embed` parameter embeds linked resources in the response data. 283 * @type bool $links Whether the response links are added to the response data as `_links`. 284 * } 285 * 286 * @phpstan-return Data_Processing 287 */ 288 public function get_data_processing() { 289 return $this->data_processing; 290 } 291 292 /** 293 * Sets whether each data processing feature is on for the response. 294 * 295 * The setting takes the form of the `data_processing` route option: `false` turns off every 296 * feature, and an array turns off, or on, the features it names. Embedding needs the links, so 297 * `embed` is off whenever `links` is off. 298 * 299 * @since 7.2.0 300 * 301 * @see WP_REST_Server::resolve_data_processing() 302 * 303 * @param bool|array<string, bool> $processing Whether every feature is on, or whether the `fields`, `embed` 304 * and `links` features are on. A feature not named stays on. 305 * 306 * @phpstan-param bool|array{fields?: bool, embed?: bool, links?: bool} $processing 307 */ 308 public function set_data_processing( $processing ) { 309 $this->data_processing = WP_REST_Server::resolve_data_processing( array( 'data_processing' => $processing ) ); 310 } 311 312 /** 313 * Checks if the response is an error, i.e. >= 400 response code. 314 * 315 * @since 4.4.0 316 * 317 * @return bool Whether the response is an error. 318 */ 319 public function is_error() { 320 return $this->get_status() >= 400; 321 } 322 323 /** 324 * Retrieves a WP_Error object from the response. 325 * 326 * @since 4.4.0 327 * 328 * @return WP_Error|null WP_Error or null on not an errored response. 329 */ 330 public function as_error() { 331 if ( ! $this->is_error() ) { 332 return null; 333 } 334 335 $error = new WP_Error(); 336 337 if ( is_array( $this->get_data() ) ) { 338 $data = $this->get_data(); 339 $error->add( $data['code'], $data['message'], $data['data'] ); 340 341 if ( ! empty( $data['additional_errors'] ) ) { 342 foreach ( $data['additional_errors'] as $err ) { 343 $error->add( $err['code'], $err['message'], $err['data'] ); 344 } 345 } 346 } else { 347 $error->add( $this->get_status(), '', array( 'status' => $this->get_status() ) ); 348 } 349 350 return $error; 351 } 352 353 /** 354 * Retrieves the CURIEs (compact URIs) used for relations. 355 * 356 * @since 4.5.0 357 * 358 * @return array<string, string|bool>[] Compact URIs. 359 * 360 * @phpstan-return array<Curie> 361 */ 362 public function get_curies() { 363 $curies = array( 364 array( 365 'name' => 'wp', 366 'href' => 'https://api.w.org/{rel}', 367 'templated' => true, 368 ), 369 ); 370 371 /** 372 * Filters extra CURIEs available on REST API responses. 373 * 374 * CURIEs allow a shortened version of URI relations. This allows a more 375 * usable form for custom relations than using the full URI. These work 376 * similarly to how XML namespaces work. 377 * 378 * Registered CURIES need to specify a name and URI template. This will 379 * automatically transform URI relations into their shortened version. 380 * The shortened relation follows the format `{name}:{rel}`. `{rel}` in 381 * the URI template will be replaced with the `{rel}` part of the 382 * shortened relation. 383 * 384 * For example, a CURIE with name `example` and URI template 385 * `http://w.org/{rel}` would transform a `http://w.org/term` relation 386 * into `example:term`. 387 * 388 * Well-behaved clients should expand and normalize these back to their 389 * full URI relation, however some naive clients may not resolve these 390 * correctly, so adding new CURIEs may break backward compatibility. 391 * 392 * @since 4.5.0 393 * 394 * @param array<string, string|bool>[] $additional Additional CURIEs to register with the REST API. 395 * 396 * @phpstan-param array<Curie> $additional 397 */ 398 $additional = apply_filters( 'rest_response_link_curies', array() ); 399 400 return array_merge( $curies, $additional ); 401 } 402 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sat Nov 21 08:20:02 2026 | Cross-referenced by PHPXref |