[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/rest-api/ -> class-wp-rest-response.php (source)

   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  }


Generated : Sat Nov 21 08:20:02 2026 Cross-referenced by PHPXref