[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

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

   1  <?php
   2  /**
   3   * REST API: WP_REST_Request 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 request object.
  12   *
  13   * Contains data from the request, to be passed to the callback.
  14   *
  15   * Note: This implements ArrayAccess, and acts as an array of parameters when
  16   * used in that manner. It does not use ArrayObject (as we cannot rely on SPL),
  17   * so be aware it may have non-array behaviour in some cases.
  18   *
  19   * Note: When using features provided by ArrayAccess, be aware that WordPress deliberately
  20   * does not distinguish between arguments of the same name for different request methods.
  21   * For instance, in a request with `GET id=1` and `POST id=2`, `$request['id']` will equal
  22   * 2 (`POST`) not 1 (`GET`). For more precision between request methods, use
  23   * WP_REST_Request::get_body_params(), WP_REST_Request::get_url_params(), etc.
  24   *
  25   * @since 4.4.0
  26   *
  27   * @link https://www.php.net/manual/en/class.arrayaccess.php
  28   */
  29  class WP_REST_Request implements ArrayAccess {
  30  
  31      /**
  32       * HTTP method.
  33       *
  34       * @since 4.4.0
  35       * @var string
  36       */
  37      protected $method = '';
  38  
  39      /**
  40       * Parameters passed to the request.
  41       *
  42       * These typically come from the `$_GET`, `$_POST` and `$_FILES`
  43       * superglobals when being created from the global scope.
  44       *
  45       * @since 4.4.0
  46       * @var array Contains GET, POST and FILES keys mapping to arrays of data.
  47       */
  48      protected $params;
  49  
  50      /**
  51       * HTTP headers for the request.
  52       *
  53       * @since 4.4.0
  54       * @var array Map of key to value. Key is always lowercase, as per HTTP specification.
  55       */
  56      protected $headers = array();
  57  
  58      /**
  59       * Body data.
  60       *
  61       * @since 4.4.0
  62       * @var string Binary data from the request.
  63       */
  64      protected $body = null;
  65  
  66      /**
  67       * Route matched for the request.
  68       *
  69       * @since 4.4.0
  70       * @var string
  71       */
  72      protected $route;
  73  
  74      /**
  75       * Attributes (options) for the route that was matched.
  76       *
  77       * This is the options array used when the route was registered, typically
  78       * containing the callback as well as the valid methods for the route.
  79       *
  80       * @since 4.4.0
  81       * @var array Attributes for the request.
  82       */
  83      protected $attributes = array();
  84  
  85      /**
  86       * Used to determine if the JSON data has been parsed yet.
  87       *
  88       * Allows lazy-parsing of JSON data where possible.
  89       *
  90       * @since 4.4.0
  91       * @var bool
  92       */
  93      protected $parsed_json = false;
  94  
  95      /**
  96       * Used to determine if the body data has been parsed yet.
  97       *
  98       * @since 4.4.0
  99       * @var bool
 100       */
 101      protected $parsed_body = false;
 102  
 103      /**
 104       * Constructor.
 105       *
 106       * @since 4.4.0
 107       *
 108       * @param string $method     Optional. Request method. Default empty.
 109       * @param string $route      Optional. Request route. Default empty.
 110       * @param array  $attributes Optional. Request attributes. Default empty array.
 111       */
 112  	public function __construct( $method = '', $route = '', $attributes = array() ) {
 113          $this->params = array(
 114              'URL'      => array(),
 115              'GET'      => array(),
 116              'POST'     => array(),
 117              'FILES'    => array(),
 118  
 119              // See parse_json_params.
 120              'JSON'     => null,
 121  
 122              'defaults' => array(),
 123          );
 124  
 125          $this->set_method( $method );
 126          $this->set_route( $route );
 127          $this->set_attributes( $attributes );
 128      }
 129  
 130      /**
 131       * Retrieves the HTTP method for the request.
 132       *
 133       * @since 4.4.0
 134       *
 135       * @return string HTTP method.
 136       */
 137  	public function get_method() {
 138          return $this->method;
 139      }
 140  
 141      /**
 142       * Sets HTTP method for the request.
 143       *
 144       * @since 4.4.0
 145       *
 146       * @param string $method HTTP method.
 147       */
 148  	public function set_method( $method ) {
 149          $this->method = strtoupper( $method );
 150      }
 151  
 152      /**
 153       * Retrieves all headers from the request.
 154       *
 155       * @since 4.4.0
 156       *
 157       * @return array Map of key to value. Key is always lowercase, as per HTTP specification.
 158       */
 159  	public function get_headers() {
 160          return $this->headers;
 161      }
 162  
 163      /**
 164       * Canonicalizes the header name.
 165       *
 166       * Ensures that header names are always treated the same regardless of
 167       * source. Header names are always case insensitive.
 168       *
 169       * Note that we treat `-` (dashes) and `_` (underscores) as the same
 170       * character, as per header parsing rules in both Apache and nginx.
 171       *
 172       * @link https://stackoverflow.com/q/18185366
 173       * @link https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#missing-disappearing-http-headers
 174       * @link https://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers
 175       *
 176       * @since 4.4.0
 177       *
 178       * @param string $key Header name.
 179       * @return string Canonicalized name.
 180       */
 181  	public static function canonicalize_header_name( $key ) {
 182          $key = strtolower( $key );
 183          $key = str_replace( '-', '_', $key );
 184  
 185          return $key;
 186      }
 187  
 188      /**
 189       * Retrieves the given header from the request.
 190       *
 191       * If the header has multiple values, they will be concatenated with a comma
 192       * as per the HTTP specification. Be aware that some non-compliant headers
 193       * (notably cookie headers) cannot be joined this way.
 194       *
 195       * @since 4.4.0
 196       *
 197       * @param string $key Header name, will be canonicalized to lowercase.
 198       * @return string|null String value if set, null otherwise.
 199       */
 200  	public function get_header( $key ) {
 201          $key = $this->canonicalize_header_name( $key );
 202  
 203          if ( ! isset( $this->headers[ $key ] ) ) {
 204              return null;
 205          }
 206  
 207          return implode( ',', $this->headers[ $key ] );
 208      }
 209  
 210      /**
 211       * Retrieves header values from the request.
 212       *
 213       * @since 4.4.0
 214       *
 215       * @param string $key Header name, will be canonicalized to lowercase.
 216       * @return array|null List of string values if set, null otherwise.
 217       */
 218  	public function get_header_as_array( $key ) {
 219          $key = $this->canonicalize_header_name( $key );
 220  
 221          if ( ! isset( $this->headers[ $key ] ) ) {
 222              return null;
 223          }
 224  
 225          return $this->headers[ $key ];
 226      }
 227  
 228      /**
 229       * Sets the header on request.
 230       *
 231       * @since 4.4.0
 232       *
 233       * @param string $key   Header name.
 234       * @param string $value Header value, or list of values.
 235       */
 236  	public function set_header( $key, $value ) {
 237          $key   = $this->canonicalize_header_name( $key );
 238          $value = (array) $value;
 239  
 240          $this->headers[ $key ] = $value;
 241      }
 242  
 243      /**
 244       * Appends a header value for the given header.
 245       *
 246       * @since 4.4.0
 247       *
 248       * @param string $key   Header name.
 249       * @param string $value Header value, or list of values.
 250       */
 251  	public function add_header( $key, $value ) {
 252          $key   = $this->canonicalize_header_name( $key );
 253          $value = (array) $value;
 254  
 255          if ( ! isset( $this->headers[ $key ] ) ) {
 256              $this->headers[ $key ] = array();
 257          }
 258  
 259          $this->headers[ $key ] = array_merge( $this->headers[ $key ], $value );
 260      }
 261  
 262      /**
 263       * Removes all values for a header.
 264       *
 265       * @since 4.4.0
 266       *
 267       * @param string $key Header name.
 268       */
 269  	public function remove_header( $key ) {
 270          $key = $this->canonicalize_header_name( $key );
 271          unset( $this->headers[ $key ] );
 272      }
 273  
 274      /**
 275       * Sets headers on the request.
 276       *
 277       * @since 4.4.0
 278       *
 279       * @param array $headers  Map of header name to value.
 280       * @param bool  $override If true, replace the request's headers. Otherwise, merge with existing.
 281       */
 282  	public function set_headers( $headers, $override = true ) {
 283          if ( true === $override ) {
 284              $this->headers = array();
 285          }
 286  
 287          foreach ( $headers as $key => $value ) {
 288              $this->set_header( $key, $value );
 289          }
 290      }
 291  
 292      /**
 293       * Retrieves the content-type of the request.
 294       *
 295       * @since 4.4.0
 296       *
 297       * @return array|null Map containing 'value' and 'parameters' keys
 298       *                    or null when no valid content-type header was
 299       *                    available.
 300       */
 301  	public function get_content_type() {
 302          $value = $this->get_header( 'content-type' );
 303          if ( empty( $value ) ) {
 304              return null;
 305          }
 306  
 307          $parameters = '';
 308          if ( strpos( $value, ';' ) ) {
 309              list( $value, $parameters ) = explode( ';', $value, 2 );
 310          }
 311  
 312          $value = strtolower( $value );
 313          if ( false === strpos( $value, '/' ) ) {
 314              return null;
 315          }
 316  
 317          // Parse type and subtype out.
 318          list( $type, $subtype ) = explode( '/', $value, 2 );
 319  
 320          $data = compact( 'value', 'type', 'subtype', 'parameters' );
 321          $data = array_map( 'trim', $data );
 322  
 323          return $data;
 324      }
 325  
 326      /**
 327       * Retrieves the parameter priority order.
 328       *
 329       * Used when checking parameters in get_param().
 330       *
 331       * @since 4.4.0
 332       *
 333       * @return string[] Array of types to check, in order of priority.
 334       */
 335  	protected function get_parameter_order() {
 336          $order = array();
 337  
 338          $content_type = $this->get_content_type();
 339          if ( isset( $content_type['value'] ) && 'application/json' === $content_type['value'] ) {
 340              $order[] = 'JSON';
 341          }
 342  
 343          $this->parse_json_params();
 344  
 345          // Ensure we parse the body data.
 346          $body = $this->get_body();
 347  
 348          if ( 'POST' !== $this->method && ! empty( $body ) ) {
 349              $this->parse_body_params();
 350          }
 351  
 352          $accepts_body_data = array( 'POST', 'PUT', 'PATCH', 'DELETE' );
 353          if ( in_array( $this->method, $accepts_body_data, true ) ) {
 354              $order[] = 'POST';
 355          }
 356  
 357          $order[] = 'GET';
 358          $order[] = 'URL';
 359          $order[] = 'defaults';
 360  
 361          /**
 362           * Filters the parameter order.
 363           *
 364           * The order affects which parameters are checked when using get_param() and family.
 365           * This acts similarly to PHP's `request_order` setting.
 366           *
 367           * @since 4.4.0
 368           *
 369           * @param string[]        $order Array of types to check, in order of priority.
 370           * @param WP_REST_Request $this  The request object.
 371           */
 372          return apply_filters( 'rest_request_parameter_order', $order, $this );
 373      }
 374  
 375      /**
 376       * Retrieves a parameter from the request.
 377       *
 378       * @since 4.4.0
 379       *
 380       * @param string $key Parameter name.
 381       * @return mixed|null Value if set, null otherwise.
 382       */
 383  	public function get_param( $key ) {
 384          $order = $this->get_parameter_order();
 385  
 386          foreach ( $order as $type ) {
 387              // Determine if we have the parameter for this type.
 388              if ( isset( $this->params[ $type ][ $key ] ) ) {
 389                  return $this->params[ $type ][ $key ];
 390              }
 391          }
 392  
 393          return null;
 394      }
 395  
 396      /**
 397       * Checks if a parameter exists in the request.
 398       *
 399       * This allows distinguishing between an omitted parameter,
 400       * and a parameter specifically set to null.
 401       *
 402       * @since 5.3.0
 403       *
 404       * @param string $key Parameter name.
 405       * @return bool True if a param exists for the given key.
 406       */
 407  	public function has_param( $key ) {
 408          $order = $this->get_parameter_order();
 409  
 410          foreach ( $order as $type ) {
 411              if ( is_array( $this->params[ $type ] ) && array_key_exists( $key, $this->params[ $type ] ) ) {
 412                  return true;
 413              }
 414          }
 415  
 416          return false;
 417      }
 418  
 419      /**
 420       * Sets a parameter on the request.
 421       *
 422       * If the given parameter key exists in any parameter type an update will take place,
 423       * otherwise a new param will be created in the first parameter type (respecting
 424       * get_parameter_order()).
 425       *
 426       * @since 4.4.0
 427       *
 428       * @param string $key   Parameter name.
 429       * @param mixed  $value Parameter value.
 430       */
 431  	public function set_param( $key, $value ) {
 432          $order     = $this->get_parameter_order();
 433          $found_key = false;
 434  
 435          foreach ( $order as $type ) {
 436              if ( 'defaults' !== $type && is_array( $this->params[ $type ] ) && array_key_exists( $key, $this->params[ $type ] ) ) {
 437                  $this->params[ $type ][ $key ] = $value;
 438                  $found_key                     = true;
 439              }
 440          }
 441  
 442          if ( ! $found_key ) {
 443              $this->params[ $order[0] ][ $key ] = $value;
 444          }
 445      }
 446  
 447      /**
 448       * Retrieves merged parameters from the request.
 449       *
 450       * The equivalent of get_param(), but returns all parameters for the request.
 451       * Handles merging all the available values into a single array.
 452       *
 453       * @since 4.4.0
 454       *
 455       * @return array Map of key to value.
 456       */
 457  	public function get_params() {
 458          $order = $this->get_parameter_order();
 459          $order = array_reverse( $order, true );
 460  
 461          $params = array();
 462          foreach ( $order as $type ) {
 463              // array_merge() / the "+" operator will mess up
 464              // numeric keys, so instead do a manual foreach.
 465              foreach ( (array) $this->params[ $type ] as $key => $value ) {
 466                  $params[ $key ] = $value;
 467              }
 468          }
 469  
 470          return $params;
 471      }
 472  
 473      /**
 474       * Retrieves parameters from the route itself.
 475       *
 476       * These are parsed from the URL using the regex.
 477       *
 478       * @since 4.4.0
 479       *
 480       * @return array Parameter map of key to value.
 481       */
 482  	public function get_url_params() {
 483          return $this->params['URL'];
 484      }
 485  
 486      /**
 487       * Sets parameters from the route.
 488       *
 489       * Typically, this is set after parsing the URL.
 490       *
 491       * @since 4.4.0
 492       *
 493       * @param array $params Parameter map of key to value.
 494       */
 495  	public function set_url_params( $params ) {
 496          $this->params['URL'] = $params;
 497      }
 498  
 499      /**
 500       * Retrieves parameters from the query string.
 501       *
 502       * These are the parameters you'd typically find in `$_GET`.
 503       *
 504       * @since 4.4.0
 505       *
 506       * @return array Parameter map of key to value
 507       */
 508  	public function get_query_params() {
 509          return $this->params['GET'];
 510      }
 511  
 512      /**
 513       * Sets parameters from the query string.
 514       *
 515       * Typically, this is set from `$_GET`.
 516       *
 517       * @since 4.4.0
 518       *
 519       * @param array $params Parameter map of key to value.
 520       */
 521  	public function set_query_params( $params ) {
 522          $this->params['GET'] = $params;
 523      }
 524  
 525      /**
 526       * Retrieves parameters from the body.
 527       *
 528       * These are the parameters you'd typically find in `$_POST`.
 529       *
 530       * @since 4.4.0
 531       *
 532       * @return array Parameter map of key to value.
 533       */
 534  	public function get_body_params() {
 535          return $this->params['POST'];
 536      }
 537  
 538      /**
 539       * Sets parameters from the body.
 540       *
 541       * Typically, this is set from `$_POST`.
 542       *
 543       * @since 4.4.0
 544       *
 545       * @param array $params Parameter map of key to value.
 546       */
 547  	public function set_body_params( $params ) {
 548          $this->params['POST'] = $params;
 549      }
 550  
 551      /**
 552       * Retrieves multipart file parameters from the body.
 553       *
 554       * These are the parameters you'd typically find in `$_FILES`.
 555       *
 556       * @since 4.4.0
 557       *
 558       * @return array Parameter map of key to value
 559       */
 560  	public function get_file_params() {
 561          return $this->params['FILES'];
 562      }
 563  
 564      /**
 565       * Sets multipart file parameters from the body.
 566       *
 567       * Typically, this is set from `$_FILES`.
 568       *
 569       * @since 4.4.0
 570       *
 571       * @param array $params Parameter map of key to value.
 572       */
 573  	public function set_file_params( $params ) {
 574          $this->params['FILES'] = $params;
 575      }
 576  
 577      /**
 578       * Retrieves the default parameters.
 579       *
 580       * These are the parameters set in the route registration.
 581       *
 582       * @since 4.4.0
 583       *
 584       * @return array Parameter map of key to value
 585       */
 586  	public function get_default_params() {
 587          return $this->params['defaults'];
 588      }
 589  
 590      /**
 591       * Sets default parameters.
 592       *
 593       * These are the parameters set in the route registration.
 594       *
 595       * @since 4.4.0
 596       *
 597       * @param array $params Parameter map of key to value.
 598       */
 599  	public function set_default_params( $params ) {
 600          $this->params['defaults'] = $params;
 601      }
 602  
 603      /**
 604       * Retrieves the request body content.
 605       *
 606       * @since 4.4.0
 607       *
 608       * @return string Binary data from the request body.
 609       */
 610  	public function get_body() {
 611          return $this->body;
 612      }
 613  
 614      /**
 615       * Sets body content.
 616       *
 617       * @since 4.4.0
 618       *
 619       * @param string $data Binary data from the request body.
 620       */
 621  	public function set_body( $data ) {
 622          $this->body = $data;
 623  
 624          // Enable lazy parsing.
 625          $this->parsed_json    = false;
 626          $this->parsed_body    = false;
 627          $this->params['JSON'] = null;
 628      }
 629  
 630      /**
 631       * Retrieves the parameters from a JSON-formatted body.
 632       *
 633       * @since 4.4.0
 634       *
 635       * @return array Parameter map of key to value.
 636       */
 637  	public function get_json_params() {
 638          // Ensure the parameters have been parsed out.
 639          $this->parse_json_params();
 640  
 641          return $this->params['JSON'];
 642      }
 643  
 644      /**
 645       * Parses the JSON parameters.
 646       *
 647       * Avoids parsing the JSON data until we need to access it.
 648       *
 649       * @since 4.4.0
 650       * @since 4.7.0 Returns error instance if value cannot be decoded.
 651       * @return true|WP_Error True if the JSON data was passed or no JSON data was provided, WP_Error if invalid JSON was passed.
 652       */
 653  	protected function parse_json_params() {
 654          if ( $this->parsed_json ) {
 655              return true;
 656          }
 657  
 658          $this->parsed_json = true;
 659  
 660          // Check that we actually got JSON.
 661          $content_type = $this->get_content_type();
 662  
 663          if ( empty( $content_type ) || 'application/json' !== $content_type['value'] ) {
 664              return true;
 665          }
 666  
 667          $body = $this->get_body();
 668          if ( empty( $body ) ) {
 669              return true;
 670          }
 671  
 672          $params = json_decode( $body, true );
 673  
 674          /*
 675           * Check for a parsing error.
 676           */
 677          if ( null === $params && JSON_ERROR_NONE !== json_last_error() ) {
 678              // Ensure subsequent calls receive error instance.
 679              $this->parsed_json = false;
 680  
 681              $error_data = array(
 682                  'status'             => WP_Http::BAD_REQUEST,
 683                  'json_error_code'    => json_last_error(),
 684                  'json_error_message' => json_last_error_msg(),
 685              );
 686  
 687              return new WP_Error( 'rest_invalid_json', __( 'Invalid JSON body passed.' ), $error_data );
 688          }
 689  
 690          $this->params['JSON'] = $params;
 691  
 692          return true;
 693      }
 694  
 695      /**
 696       * Parses the request body parameters.
 697       *
 698       * Parses out URL-encoded bodies for request methods that aren't supported
 699       * natively by PHP. In PHP 5.x, only POST has these parsed automatically.
 700       *
 701       * @since 4.4.0
 702       */
 703  	protected function parse_body_params() {
 704          if ( $this->parsed_body ) {
 705              return;
 706          }
 707  
 708          $this->parsed_body = true;
 709  
 710          /*
 711           * Check that we got URL-encoded. Treat a missing content-type as
 712           * URL-encoded for maximum compatibility.
 713           */
 714          $content_type = $this->get_content_type();
 715  
 716          if ( ! empty( $content_type ) && 'application/x-www-form-urlencoded' !== $content_type['value'] ) {
 717              return;
 718          }
 719  
 720          parse_str( $this->get_body(), $params );
 721  
 722          /*
 723           * Add to the POST parameters stored internally. If a user has already
 724           * set these manually (via `set_body_params`), don't override them.
 725           */
 726          $this->params['POST'] = array_merge( $params, $this->params['POST'] );
 727      }
 728  
 729      /**
 730       * Retrieves the route that matched the request.
 731       *
 732       * @since 4.4.0
 733       *
 734       * @return string Route matching regex.
 735       */
 736  	public function get_route() {
 737          return $this->route;
 738      }
 739  
 740      /**
 741       * Sets the route that matched the request.
 742       *
 743       * @since 4.4.0
 744       *
 745       * @param string $route Route matching regex.
 746       */
 747  	public function set_route( $route ) {
 748          $this->route = $route;
 749      }
 750  
 751      /**
 752       * Retrieves the attributes for the request.
 753       *
 754       * These are the options for the route that was matched.
 755       *
 756       * @since 4.4.0
 757       *
 758       * @return array Attributes for the request.
 759       */
 760  	public function get_attributes() {
 761          return $this->attributes;
 762      }
 763  
 764      /**
 765       * Sets the attributes for the request.
 766       *
 767       * @since 4.4.0
 768       *
 769       * @param array $attributes Attributes for the request.
 770       */
 771  	public function set_attributes( $attributes ) {
 772          $this->attributes = $attributes;
 773      }
 774  
 775      /**
 776       * Sanitizes (where possible) the params on the request.
 777       *
 778       * This is primarily based off the sanitize_callback param on each registered
 779       * argument.
 780       *
 781       * @since 4.4.0
 782       *
 783       * @return true|WP_Error True if parameters were sanitized, WP_Error if an error occurred during sanitization.
 784       */
 785  	public function sanitize_params() {
 786          $attributes = $this->get_attributes();
 787  
 788          // No arguments set, skip sanitizing.
 789          if ( empty( $attributes['args'] ) ) {
 790              return true;
 791          }
 792  
 793          $order = $this->get_parameter_order();
 794  
 795          $invalid_params = array();
 796  
 797          foreach ( $order as $type ) {
 798              if ( empty( $this->params[ $type ] ) ) {
 799                  continue;
 800              }
 801  
 802              foreach ( $this->params[ $type ] as $key => $value ) {
 803                  if ( ! isset( $attributes['args'][ $key ] ) ) {
 804                      continue;
 805                  }
 806  
 807                  $param_args = $attributes['args'][ $key ];
 808  
 809                  // If the arg has a type but no sanitize_callback attribute, default to rest_parse_request_arg.
 810                  if ( ! array_key_exists( 'sanitize_callback', $param_args ) && ! empty( $param_args['type'] ) ) {
 811                      $param_args['sanitize_callback'] = 'rest_parse_request_arg';
 812                  }
 813                  // If there's still no sanitize_callback, nothing to do here.
 814                  if ( empty( $param_args['sanitize_callback'] ) ) {
 815                      continue;
 816                  }
 817  
 818                  $sanitized_value = call_user_func( $param_args['sanitize_callback'], $value, $this, $key );
 819  
 820                  if ( is_wp_error( $sanitized_value ) ) {
 821                      $invalid_params[ $key ] = $sanitized_value->get_error_message();
 822                  } else {
 823                      $this->params[ $type ][ $key ] = $sanitized_value;
 824                  }
 825              }
 826          }
 827  
 828          if ( $invalid_params ) {
 829              return new WP_Error(
 830                  'rest_invalid_param',
 831                  /* translators: %s: List of invalid parameters. */
 832                  sprintf( __( 'Invalid parameter(s): %s' ), implode( ', ', array_keys( $invalid_params ) ) ),
 833                  array(
 834                      'status' => 400,
 835                      'params' => $invalid_params,
 836                  )
 837              );
 838          }
 839  
 840          return true;
 841      }
 842  
 843      /**
 844       * Checks whether this request is valid according to its attributes.
 845       *
 846       * @since 4.4.0
 847       *
 848       * @return bool|WP_Error True if there are no parameters to validate or if all pass validation,
 849       *                       WP_Error if required parameters are missing.
 850       */
 851  	public function has_valid_params() {
 852          // If JSON data was passed, check for errors.
 853          $json_error = $this->parse_json_params();
 854          if ( is_wp_error( $json_error ) ) {
 855              return $json_error;
 856          }
 857  
 858          $attributes = $this->get_attributes();
 859          $required   = array();
 860  
 861          $args = empty( $attributes['args'] ) ? array() : $attributes['args'];
 862  
 863          foreach ( $args as $key => $arg ) {
 864              $param = $this->get_param( $key );
 865              if ( isset( $arg['required'] ) && true === $arg['required'] && null === $param ) {
 866                  $required[] = $key;
 867              }
 868          }
 869  
 870          if ( ! empty( $required ) ) {
 871              return new WP_Error(
 872                  'rest_missing_callback_param',
 873                  /* translators: %s: List of required parameters. */
 874                  sprintf( __( 'Missing parameter(s): %s' ), implode( ', ', $required ) ),
 875                  array(
 876                      'status' => 400,
 877                      'params' => $required,
 878                  )
 879              );
 880          }
 881  
 882          /*
 883           * Check the validation callbacks for each registered arg.
 884           *
 885           * This is done after required checking as required checking is cheaper.
 886           */
 887          $invalid_params = array();
 888  
 889          foreach ( $args as $key => $arg ) {
 890  
 891              $param = $this->get_param( $key );
 892  
 893              if ( null !== $param && ! empty( $arg['validate_callback'] ) ) {
 894                  $valid_check = call_user_func( $arg['validate_callback'], $param, $this, $key );
 895  
 896                  if ( false === $valid_check ) {
 897                      $invalid_params[ $key ] = __( 'Invalid parameter.' );
 898                  }
 899  
 900                  if ( is_wp_error( $valid_check ) ) {
 901                      $invalid_params[ $key ] = $valid_check->get_error_message();
 902                  }
 903              }
 904          }
 905  
 906          if ( $invalid_params ) {
 907              return new WP_Error(
 908                  'rest_invalid_param',
 909                  /* translators: %s: List of invalid parameters. */
 910                  sprintf( __( 'Invalid parameter(s): %s' ), implode( ', ', array_keys( $invalid_params ) ) ),
 911                  array(
 912                      'status' => 400,
 913                      'params' => $invalid_params,
 914                  )
 915              );
 916          }
 917  
 918          if ( isset( $attributes['validate_callback'] ) ) {
 919              $valid_check = call_user_func( $attributes['validate_callback'], $this );
 920  
 921              if ( is_wp_error( $valid_check ) ) {
 922                  return $valid_check;
 923              }
 924  
 925              if ( false === $valid_check ) {
 926                  // A WP_Error instance is preferred, but false is supported for parity with the per-arg validate_callback.
 927                  return new WP_Error( 'rest_invalid_params', __( 'Invalid parameters.' ), array( 'status' => 400 ) );
 928              }
 929          }
 930  
 931          return true;
 932      }
 933  
 934      /**
 935       * Checks if a parameter is set.
 936       *
 937       * @since 4.4.0
 938       *
 939       * @param string $offset Parameter name.
 940       * @return bool Whether the parameter is set.
 941       */
 942  	public function offsetExists( $offset ) {
 943          $order = $this->get_parameter_order();
 944  
 945          foreach ( $order as $type ) {
 946              if ( isset( $this->params[ $type ][ $offset ] ) ) {
 947                  return true;
 948              }
 949          }
 950  
 951          return false;
 952      }
 953  
 954      /**
 955       * Retrieves a parameter from the request.
 956       *
 957       * @since 4.4.0
 958       *
 959       * @param string $offset Parameter name.
 960       * @return mixed|null Value if set, null otherwise.
 961       */
 962  	public function offsetGet( $offset ) {
 963          return $this->get_param( $offset );
 964      }
 965  
 966      /**
 967       * Sets a parameter on the request.
 968       *
 969       * @since 4.4.0
 970       *
 971       * @param string $offset Parameter name.
 972       * @param mixed  $value  Parameter value.
 973       */
 974  	public function offsetSet( $offset, $value ) {
 975          $this->set_param( $offset, $value );
 976      }
 977  
 978      /**
 979       * Removes a parameter from the request.
 980       *
 981       * @since 4.4.0
 982       *
 983       * @param string $offset Parameter name.
 984       */
 985  	public function offsetUnset( $offset ) {
 986          $order = $this->get_parameter_order();
 987  
 988          // Remove the offset from every group.
 989          foreach ( $order as $type ) {
 990              unset( $this->params[ $type ][ $offset ] );
 991          }
 992      }
 993  
 994      /**
 995       * Retrieves a WP_REST_Request object from a full URL.
 996       *
 997       * @since 4.5.0
 998       *
 999       * @param string $url URL with protocol, domain, path and query args.
1000       * @return WP_REST_Request|false WP_REST_Request object on success, false on failure.
1001       */
1002  	public static function from_url( $url ) {
1003          $bits         = parse_url( $url );
1004          $query_params = array();
1005  
1006          if ( ! empty( $bits['query'] ) ) {
1007              wp_parse_str( $bits['query'], $query_params );
1008          }
1009  
1010          $api_root = rest_url();
1011          if ( get_option( 'permalink_structure' ) && 0 === strpos( $url, $api_root ) ) {
1012              // Pretty permalinks on, and URL is under the API root.
1013              $api_url_part = substr( $url, strlen( untrailingslashit( $api_root ) ) );
1014              $route        = parse_url( $api_url_part, PHP_URL_PATH );
1015          } elseif ( ! empty( $query_params['rest_route'] ) ) {
1016              // ?rest_route=... set directly.
1017              $route = $query_params['rest_route'];
1018              unset( $query_params['rest_route'] );
1019          }
1020  
1021          $request = false;
1022          if ( ! empty( $route ) ) {
1023              $request = new WP_REST_Request( 'GET', $route );
1024              $request->set_query_params( $query_params );
1025          }
1026  
1027          /**
1028           * Filters the request generated from a URL.
1029           *
1030           * @since 4.5.0
1031           *
1032           * @param WP_REST_Request|false $request Generated request object, or false if URL
1033           *                                       could not be parsed.
1034           * @param string                $url     URL the request was generated from.
1035           */
1036          return apply_filters( 'rest_request_from_url', $request, $url );
1037      }
1038  }


Generated: Sat Sep 19 01:00:03 2020 Cross-referenced by PHPXref 0.7.1