wp-includes/rest-api/class-wp-rest-request.php

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