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