[ Index ]

PHP Cross Reference of WordPress

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


Generated: Tue Sep 17 01:00:03 2019 Cross-referenced by PHPXref 0.7.1