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

   1 <?php
   2 /**
   3  * REST API: WP_REST_Server class
   4  *
   5  * @package WordPress
   6  * @subpackage REST_API
   7  * @since 4.4.0
   8  */
   9
  10 /**
  11  * Core class used to implement the WordPress REST API server.
  12  *
  13  * @since 4.4.0
  14  */
  15 class WP_REST_Server {
  16
  17         /**
  18          * Alias for GET transport method.
  19          *
  20          * @since 4.4.0
  21          * @var string
  22          */
  23         const READABLE = 'GET';
  24
  25         /**
  26          * Alias for POST transport method.
  27          *
  28          * @since 4.4.0
  29          * @var string
  30          */
  31         const CREATABLE = 'POST';
  32
  33         /**
  34          * Alias for POST, PUT, PATCH transport methods together.
  35          *
  36          * @since 4.4.0
  37          * @var string
  38          */
  39         const EDITABLE = 'POST, PUT, PATCH';
  40
  41         /**
  42          * Alias for DELETE transport method.
  43          *
  44          * @since 4.4.0
  45          * @var string
  46          */
  47         const DELETABLE = 'DELETE';
  48
  49         /**
  50          * Alias for GET, POST, PUT, PATCH & DELETE transport methods together.
  51          *
  52          * @since 4.4.0
  53          * @var string
  54          */
  55         const ALLMETHODS = 'GET, POST, PUT, PATCH, DELETE';
  56
  57         /**
  58          * Namespaces registered to the server.
  59          *
  60          * @since 4.4.0
  61          * @access protected
  62          * @var array
  63          */
  64         protected $namespaces = array();
  65
  66         /**
  67          * Endpoints registered to the server.
  68          *
  69          * @since 4.4.0
  70          * @access protected
  71          * @var array
  72          */
  73         protected $endpoints = array();
  74
  75         /**
  76          * Options defined for the routes.
  77          *
  78          * @since 4.4.0
  79          * @access protected
  80          * @var array
  81          */
  82         protected $route_options = array();
  83
  84         /**
  85          * Instantiates the REST server.
  86          *
  87          * @since 4.4.0
  88          * @access public
  89          */
  90         public function __construct() {
  91                 $this->endpoints = array(
  92                         // Meta endpoints.
  93                         '/' => array(
  94                                 'callback' => array( $this, 'get_index' ),
  95                                 'methods' => 'GET',
  96                                 'args' => array(
  97                                         'context' => array(
  98                                                 'default' => 'view',
  99                                         ),
 100                                 ),
 101                         ),
 102                 );
 103         }
 104
 105
 106         /**
 107          * Checks the authentication headers if supplied.
 108          *
 109          * @since 4.4.0
 110          * @access public
 111          *
 112          * @return WP_Error|null WP_Error indicates unsuccessful login, null indicates successful
 113          *                       or no authentication provided
 114          */
 115         public function check_authentication() {
 116                 /**
 117                  * Pass an authentication error to the API
 118                  *
 119                  * This is used to pass a WP_Error from an authentication method back to
 120                  * the API.
 121                  *
 122                  * Authentication methods should check first if they're being used, as
 123                  * multiple authentication methods can be enabled on a site (cookies,
 124                  * HTTP basic auth, OAuth). If the authentication method hooked in is
 125                  * not actually being attempted, null should be returned to indicate
 126                  * another authentication method should check instead. Similarly,
 127                  * callbacks should ensure the value is `null` before checking for
 128                  * errors.
 129                  *
 130                  * A WP_Error instance can be returned if an error occurs, and this should
 131                  * match the format used by API methods internally (that is, the `status`
 132                  * data should be used). A callback can return `true` to indicate that
 133                  * the authentication method was used, and it succeeded.
 134                  *
 135                  * @since 4.4.0
 136                  *
 137                  * @param WP_Error|null|bool WP_Error if authentication error, null if authentication
 138                  *                              method wasn't used, true if authentication succeeded.
 139                  */
 140                 return apply_filters( 'rest_authentication_errors', null );
 141         }
 142
 143         /**
 144          * Converts an error to a response object.
 145          *
 146          * This iterates over all error codes and messages to change it into a flat
 147          * array. This enables simpler client behaviour, as it is represented as a
 148          * list in JSON rather than an object/map.
 149          *
 150          * @since 4.4.0
 151          * @access protected
 152          *
 153          * @param WP_Error $error WP_Error instance.
 154          * @return WP_REST_Response List of associative arrays with code and message keys.
 155          */
 156         protected function error_to_response( $error ) {
 157                 $error_data = $error->get_error_data();
 158
 159                 if ( is_array( $error_data ) && isset( $error_data['status'] ) ) {
 160                         $status = $error_data['status'];
 161                 } else {
 162                         $status = 500;
 163                 }
 164
 165                 $errors = array();
 166
 167                 foreach ( (array) $error->errors as $code => $messages ) {
 168                         foreach ( (array) $messages as $message ) {
 169                                 $errors[] = array( 'code' => $code, 'message' => $message, 'data' => $error->get_error_data( $code ) );
 170                         }
 171                 }
 172
 173                 $data = $errors[0];
 174                 if ( count( $errors ) > 1 ) {
 175                         // Remove the primary error.
 176                         array_shift( $errors );
 177                         $data['additional_errors'] = $errors;
 178                 }
 179
 180                 $response = new WP_REST_Response( $data, $status );
 181
 182                 return $response;
 183         }
 184
 185         /**
 186          * Retrieves an appropriate error representation in JSON.
 187          *
 188          * Note: This should only be used in WP_REST_Server::serve_request(), as it
 189          * cannot handle WP_Error internally. All callbacks and other internal methods
 190          * should instead return a WP_Error with the data set to an array that includes
 191          * a 'status' key, with the value being the HTTP status to send.
 192          *
 193          * @since 4.4.0
 194          * @access protected
 195          *
 196          * @param string $code    WP_Error-style code.
 197          * @param string $message Human-readable message.
 198          * @param int    $status  Optional. HTTP status code to send. Default null.
 199          * @return string JSON representation of the error
 200          */
 201         protected function json_error( $code, $message, $status = null ) {
 202                 if ( $status ) {
 203                         $this->set_status( $status );
 204                 }
 205
 206                 $error = compact( 'code', 'message' );
 207
 208                 return wp_json_encode( $error );
 209         }
 210
 211         /**
 212          * Handles serving an API request.
 213          *
 214          * Matches the current server URI to a route and runs the first matching
 215          * callback then outputs a JSON representation of the returned value.
 216          *
 217          * @since 4.4.0
 218          * @access public
 219          *
 220          * @see WP_REST_Server::dispatch()
 221          *
 222          * @param string $path Optional. The request route. If not set, `$_SERVER['PATH_INFO']` will be used.
 223          *                     Default null.
 224          * @return false|null Null if not served and a HEAD request, false otherwise.
 225          */
 226         public function serve_request( $path = null ) {
 227                 $content_type = isset( $_GET['_jsonp'] ) ? 'application/javascript' : 'application/json';
 228                 $this->send_header( 'Content-Type', $content_type . '; charset=' . get_option( 'blog_charset' ) );
 229
 230                 /*
 231                  * Mitigate possible JSONP Flash attacks.
 232                  *
 233                  * http://miki.it/blog/2014/7/8/abusing-jsonp-with-rosetta-flash/
 234                  */
 235                 $this->send_header( 'X-Content-Type-Options', 'nosniff' );
 236                 $this->send_header( 'Access-Control-Expose-Headers', 'X-WP-Total, X-WP-TotalPages' );
 237                 $this->send_header( 'Access-Control-Allow-Headers', 'Authorization' );
 238
 239                 /**
 240                  * Send nocache headers on authenticated requests.
 241                  *
 242                  * @since 4.4.0
 243                  *
 244                  * @param bool $rest_send_nocache_headers Whether to send no-cache headers.
 245                  */
 246                 $send_no_cache_headers = apply_filters( 'rest_send_nocache_headers', is_user_logged_in() );
 247                 if ( $send_no_cache_headers ) {
 248                         foreach ( wp_get_nocache_headers() as $header => $header_value ) {
 249                                 $this->send_header( $header, $header_value );
 250                         }
 251                 }
 252
 253                 /**
 254                  * Filter whether the REST API is enabled.
 255                  *
 256                  * @since 4.4.0
 257                  *
 258                  * @param bool $rest_enabled Whether the REST API is enabled. Default true.
 259                  */
 260                 $enabled = apply_filters( 'rest_enabled', true );
 261
 262                 /**
 263                  * Filter whether jsonp is enabled.
 264                  *
 265                  * @since 4.4.0
 266                  *
 267                  * @param bool $jsonp_enabled Whether jsonp is enabled. Default true.
 268                  */
 269                 $jsonp_enabled = apply_filters( 'rest_jsonp_enabled', true );
 270
 271                 $jsonp_callback = null;
 272
 273                 if ( ! $enabled ) {
 274                         echo $this->json_error( 'rest_disabled', __( 'The REST API is disabled on this site.' ), 404 );
 275                         return false;
 276                 }
 277                 if ( isset( $_GET['_jsonp'] ) ) {
 278                         if ( ! $jsonp_enabled ) {
 279                                 echo $this->json_error( 'rest_callback_disabled', __( 'JSONP support is disabled on this site.' ), 400 );
 280                                 return false;
 281                         }
 282
 283                         // Check for invalid characters (only alphanumeric allowed).
 284                         if ( is_string( $_GET['_jsonp'] ) ) {
 285                                 $jsonp_callback = preg_replace( '/[^\w\.]/', '', wp_unslash( $_GET['_jsonp'] ), -1, $illegal_char_count );
 286                                 if ( 0 !== $illegal_char_count ) {
 287                                         $jsonp_callback = null;
 288                                 }
 289                         }
 290                         if ( null === $jsonp_callback ) {
 291                                 echo $this->json_error( 'rest_callback_invalid', __( 'The JSONP callback function is invalid.' ), 400 );
 292                                 return false;
 293                         }
 294                 }
 295
 296                 if ( empty( $path ) ) {
 297                         if ( isset( $_SERVER['PATH_INFO'] ) ) {
 298                                 $path = $_SERVER['PATH_INFO'];
 299                         } else {
 300                                 $path = '/';
 301                         }
 302                 }
 303
 304                 $request = new WP_REST_Request( $_SERVER['REQUEST_METHOD'], $path );
 305
 306                 $request->set_query_params( $_GET );
 307                 $request->set_body_params( $_POST );
 308                 $request->set_file_params( $_FILES );
 309                 $request->set_headers( $this->get_headers( $_SERVER ) );
 310                 $request->set_body( $this->get_raw_data() );
 311
 312                 /*
 313                  * HTTP method override for clients that can't use PUT/PATCH/DELETE. First, we check
 314                  * $_GET['_method']. If that is not set, we check for the HTTP_X_HTTP_METHOD_OVERRIDE
 315                  * header.
 316                  */
 317                 if ( isset( $_GET['_method'] ) ) {
 318                         $request->set_method( $_GET['_method'] );
 319                 } elseif ( isset( $_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'] ) ) {
 320                         $request->set_method( $_SERVER['HTTP_X_HTTP_METHOD_OVERRIDE'] );
 321                 }
 322
 323                 $result = $this->check_authentication();
 324
 325                 if ( ! is_wp_error( $result ) ) {
 326                         $result = $this->dispatch( $request );
 327                 }
 328
 329                 // Normalize to either WP_Error or WP_REST_Response...
 330                 $result = rest_ensure_response( $result );
 331
 332                 // ...then convert WP_Error across.
 333                 if ( is_wp_error( $result ) ) {
 334                         $result = $this->error_to_response( $result );
 335                 }
 336
 337                 /**
 338                  * Filter the API response.
 339                  *
 340                  * Allows modification of the response before returning.
 341                  *
 342                  * @since 4.4.0
 343                  *
 344                  * @param WP_HTTP_Response $result  Result to send to the client. Usually a WP_REST_Response.
 345                  * @param WP_REST_Server   $this    Server instance.
 346                  * @param WP_REST_Request  $request Request used to generate the response.
 347                  */
 348                 $result = apply_filters( 'rest_post_dispatch', rest_ensure_response( $result ), $this, $request );
 349
 350                 // Wrap the response in an envelope if asked for.
 351                 if ( isset( $_GET['_envelope'] ) ) {
 352                         $result = $this->envelope_response( $result, isset( $_GET['_embed'] ) );
 353                 }
 354
 355                 // Send extra data from response objects.
 356                 $headers = $result->get_headers();
 357                 $this->send_headers( $headers );
 358
 359                 $code = $result->get_status();
 360                 $this->set_status( $code );
 361
 362                 /**
 363                  * Filter whether the request has already been served.
 364                  *
 365                  * Allow sending the request manually - by returning true, the API result
 366                  * will not be sent to the client.
 367                  *
 368                  * @since 4.4.0
 369                  *
 370                  * @param bool             $served  Whether the request has already been served.
 371                  *                                           Default false.
 372                  * @param WP_HTTP_Response $result  Result to send to the client. Usually a WP_REST_Response.
 373                  * @param WP_REST_Request  $request Request used to generate the response.
 374                  * @param WP_REST_Server   $this    Server instance.
 375                  */
 376                 $served = apply_filters( 'rest_pre_serve_request', false, $result, $request, $this );
 377
 378                 if ( ! $served ) {
 379                         if ( 'HEAD' === $request->get_method() ) {
 380                                 return null;
 381                         }
 382
 383                         // Embed links inside the request.
 384                         $result = $this->response_to_data( $result, isset( $_GET['_embed'] ) );
 385
 386                         $result = wp_json_encode( $result );
 387
 388                         $json_error_message = $this->get_json_last_error();
 389                         if ( $json_error_message ) {
 390                                 $json_error_obj = new WP_Error( 'rest_encode_error', $json_error_message, array( 'status' => 500 ) );
 391                                 $result = $this->error_to_response( $json_error_obj );
 392                                 $result = wp_json_encode( $result->data[0] );
 393                         }
 394
 395                         if ( $jsonp_callback ) {
 396                                 // Prepend '/**/' to mitigate possible JSONP Flash attacks
 397                                 // http://miki.it/blog/2014/7/8/abusing-jsonp-with-rosetta-flash/
 398                                 echo '/**/' . $jsonp_callback . '(' . $result . ')';
 399                         } else {
 400                                 echo $result;
 401                         }
 402                 }
 403                 return null;
 404         }
 405
 406         /**
 407          * Converts a response to data to send.
 408          *
 409          * @since 4.4.0
 410          * @access public
 411          *
 412          * @param WP_REST_Response $response Response object.
 413          * @param bool             $embed    Whether links should be embedded.
 414          * @return array {
 415          *     Data with sub-requests embedded.
 416          *
 417          *     @type array [$_links]    Links.
 418          *     @type array [$_embedded] Embeddeds.
 419          * }
 420          */
 421         public function response_to_data( $response, $embed ) {
 422                 $data  = $response->get_data();
 423                 $links = $this->get_response_links( $response );
 424
 425                 if ( ! empty( $links ) ) {
 426                         // Convert links to part of the data.
 427                         $data['_links'] = $links;
 428                 }
 429                 if ( $embed ) {
 430                         // Determine if this is a numeric array.
 431                         if ( wp_is_numeric_array( $data ) ) {
 432                                 $data = array_map( array( $this, 'embed_links' ), $data );
 433                         } else {
 434                                 $data = $this->embed_links( $data );
 435                         }
 436                 }
 437
 438                 return $data;
 439         }
 440
 441         /**
 442          * Retrieves links from a response.
 443          *
 444          * Extracts the links from a response into a structured hash, suitable for
 445          * direct output.
 446          *
 447          * @since 4.4.0
 448          * @access public
 449          * @static
 450          *
 451          * @param WP_REST_Response $response Response to extract links from.
 452          * @return array Map of link relation to list of link hashes.
 453          */
 454         public static function get_response_links( $response ) {
 455                 $links = $response->get_links();
 456
 457                 if ( empty( $links ) ) {
 458                         return array();
 459                 }
 460
 461                 // Convert links to part of the data.
 462                 $data = array();
 463                 foreach ( $links as $rel => $items ) {
 464                         $data[ $rel ] = array();
 465
 466                         foreach ( $items as $item ) {
 467                                 $attributes = $item['attributes'];
 468                                 $attributes['href'] = $item['href'];
 469                                 $data[ $rel ][] = $attributes;
 470                         }
 471                 }
 472
 473                 return $data;
 474         }
 475
 476         /**
 477          * Embeds the links from the data into the request.
 478          *
 479          * @since 4.4.0
 480          * @access protected
 481          *
 482          * @param array $data Data from the request.
 483          * @return array {
 484          *     Data with sub-requests embedded.
 485          *
 486          *     @type array [$_links]    Links.
 487          *     @type array [$_embedded] Embeddeds.
 488          * }
 489          */
 490         protected function embed_links( $data ) {
 491                 if ( empty( $data['_links'] ) ) {
 492                         return $data;
 493                 }
 494
 495                 $embedded = array();
 496                 $api_root = rest_url();
 497
 498                 foreach ( $data['_links'] as $rel => $links ) {
 499                         // Ignore links to self, for obvious reasons.
 500                         if ( 'self' === $rel ) {
 501                                 continue;
 502                         }
 503
 504                         $embeds = array();
 505
 506                         foreach ( $links as $item ) {
 507                                 // Determine if the link is embeddable.
 508                                 if ( empty( $item['embeddable'] ) || strpos( $item['href'], $api_root ) !== 0 ) {
 509                                         // Ensure we keep the same order.
 510                                         $embeds[] = array();
 511                                         continue;
 512                                 }
 513
 514                                 // Run through our internal routing and serve.
 515                                 $route = substr( $item['href'], strlen( untrailingslashit( $api_root ) ) );
 516                                 $query_params = array();
 517
 518                                 // Parse out URL query parameters.
 519                                 $parsed = parse_url( $route );
 520                                 if ( empty( $parsed['path'] ) ) {
 521                                         $embeds[] = array();
 522                                         continue;
 523                                 }
 524
 525                                 if ( ! empty( $parsed['query'] ) ) {
 526                                         parse_str( $parsed['query'], $query_params );
 527
 528                                         // Ensure magic quotes are stripped.
 529                                         if ( get_magic_quotes_gpc() ) {
 530                                                 $query_params = stripslashes_deep( $query_params );
 531                                         }
 532                                 }
 533
 534                                 // Embedded resources get passed context=embed.
 535                                 if ( empty( $query_params['context'] ) ) {
 536                                         $query_params['context'] = 'embed';
 537                                 }
 538
 539                                 $request = new WP_REST_Request( 'GET', $parsed['path'] );
 540
 541                                 $request->set_query_params( $query_params );
 542                                 $response = $this->dispatch( $request );
 543
 544                                 $embeds[] = $this->response_to_data( $response, false );
 545                         }
 546
 547                         // Determine if any real links were found.
 548                         $has_links = count( array_filter( $embeds ) );
 549                         if ( $has_links ) {
 550                                 $embedded[ $rel ] = $embeds;
 551                         }
 552                 }
 553
 554                 if ( ! empty( $embedded ) ) {
 555                         $data['_embedded'] = $embedded;
 556                 }
 557
 558                 return $data;
 559         }
 560
 561         /**
 562          * Wraps the response in an envelope.
 563          *
 564          * The enveloping technique is used to work around browser/client
 565          * compatibility issues. Essentially, it converts the full HTTP response to
 566          * data instead.
 567          *
 568          * @since 4.4.0
 569          * @access public
 570          *
 571          * @param WP_REST_Response $response Response object.
 572          * @param bool             $embed    Whether links should be embedded.
 573          * @return WP_REST_Response New response with wrapped data
 574          */
 575         public function envelope_response( $response, $embed ) {
 576                 $envelope = array(
 577                         'body'    => $this->response_to_data( $response, $embed ),
 578                         'status'  => $response->get_status(),
 579                         'headers' => $response->get_headers(),
 580                 );
 581
 582                 /**
 583                  * Filter the enveloped form of a response.
 584                  *
 585                  * @since 4.4.0
 586                  *
 587                  * @param array            $envelope Envelope data.
 588                  * @param WP_REST_Response $response Original response data.
 589                  */
 590                 $envelope = apply_filters( 'rest_envelope_response', $envelope, $response );
 591
 592                 // Ensure it's still a response and return.
 593                 return rest_ensure_response( $envelope );
 594         }
 595
 596         /**
 597          * Registers a route to the server.
 598          *
 599          * @since 4.4.0
 600          * @access public
 601          *
 602          * @param string $namespace  Namespace.
 603          * @param string $route      The REST route.
 604          * @param array  $route_args Route arguments.
 605          * @param bool   $override   Optional. Whether the route should be overriden if it already exists.
 606          *                           Default false.
 607          */
 608         public function register_route( $namespace, $route, $route_args, $override = false ) {
 609                 if ( ! isset( $this->namespaces[ $namespace ] ) ) {
 610                         $this->namespaces[ $namespace ] = array();
 611
 612                         $this->register_route( $namespace, '/' . $namespace, array(
 613                                 array(
 614                                         'methods' => self::READABLE,
 615                                         'callback' => array( $this, 'get_namespace_index' ),
 616                                         'args' => array(
 617                                                 'namespace' => array(
 618                                                         'default' => $namespace,
 619                                                 ),
 620                                                 'context' => array(
 621                                                         'default' => 'view',
 622                                                 ),
 623                                         ),
 624                                 ),
 625                         ) );
 626                 }
 627
 628                 // Associative to avoid double-registration.
 629                 $this->namespaces[ $namespace ][ $route ] = true;
 630                 $route_args['namespace'] = $namespace;
 631
 632                 if ( $override || empty( $this->endpoints[ $route ] ) ) {
 633                         $this->endpoints[ $route ] = $route_args;
 634                 } else {
 635                         $this->endpoints[ $route ] = array_merge( $this->endpoints[ $route ], $route_args );
 636                 }
 637         }
 638
 639         /**
 640          * Retrieves the route map.
 641          *
 642          * The route map is an associative array with path regexes as the keys. The
 643          * value is an indexed array with the callback function/method as the first
 644          * item, and a bitmask of HTTP methods as the second item (see the class
 645          * constants).
 646          *
 647          * Each route can be mapped to more than one callback by using an array of
 648          * the indexed arrays. This allows mapping e.g. GET requests to one callback
 649          * and POST requests to another.
 650          *
 651          * Note that the path regexes (array keys) must have @ escaped, as this is
 652          * used as the delimiter with preg_match()
 653          *
 654          * @since 4.4.0
 655          * @access public
 656          *
 657          * @return array `'/path/regex' => array( $callback, $bitmask )` or
 658          *               `'/path/regex' => array( array( $callback, $bitmask ), ...)`.
 659          */
 660         public function get_routes() {
 661
 662                 /**
 663                  * Filter the array of available endpoints.
 664                  *
 665                  * @since 4.4.0
 666                  *
 667                  * @param array $endpoints The available endpoints. An array of matching regex patterns, each mapped
 668                  *                         to an array of callbacks for the endpoint. These take the format
 669                  *                         `'/path/regex' => array( $callback, $bitmask )` or
 670                  *                         `'/path/regex' => array( array( $callback, $bitmask ).
 671                  */
 672                 $endpoints = apply_filters( 'rest_endpoints', $this->endpoints );
 673
 674                 // Normalise the endpoints.
 675                 $defaults = array(
 676                         'methods'       => '',
 677                         'accept_json'   => false,
 678                         'accept_raw'    => false,
 679                         'show_in_index' => true,
 680                         'args'          => array(),
 681                 );
 682
 683                 foreach ( $endpoints as $route => &$handlers ) {
 684
 685                         if ( isset( $handlers['callback'] ) ) {
 686                                 // Single endpoint, add one deeper.
 687                                 $handlers = array( $handlers );
 688                         }
 689
 690                         if ( ! isset( $this->route_options[ $route ] ) ) {
 691                                 $this->route_options[ $route ] = array();
 692                         }
 693
 694                         foreach ( $handlers as $key => &$handler ) {
 695
 696                                 if ( ! is_numeric( $key ) ) {
 697                                         // Route option, move it to the options.
 698                                         $this->route_options[ $route ][ $key ] = $handler;
 699                                         unset( $handlers[ $key ] );
 700                                         continue;
 701                                 }
 702
 703                                 $handler = wp_parse_args( $handler, $defaults );
 704
 705                                 // Allow comma-separated HTTP methods.
 706                                 if ( is_string( $handler['methods'] ) ) {
 707                                         $methods = explode( ',', $handler['methods'] );
 708                                 } else if ( is_array( $handler['methods'] ) ) {
 709                                         $methods = $handler['methods'];
 710                                 } else {
 711                                         $methods = array();
 712                                 }
 713
 714                                 $handler['methods'] = array();
 715
 716                                 foreach ( $methods as $method ) {
 717                                         $method = strtoupper( trim( $method ) );
 718                                         $handler['methods'][ $method ] = true;
 719                                 }
 720                         }
 721                 }
 722                 return $endpoints;
 723         }
 724
 725         /**
 726          * Retrieves namespaces registered on the server.
 727          *
 728          * @since 4.4.0
 729          * @access public
 730          *
 731          * @return array List of registered namespaces.
 732          */
 733         public function get_namespaces() {
 734                 return array_keys( $this->namespaces );
 735         }
 736
 737         /**
 738          * Retrieves specified options for a route.
 739          *
 740          * @since 4.4.0
 741          * @access public
 742          *
 743          * @param string $route Route pattern to fetch options for.
 744          * @return array|null Data as an associative array if found, or null if not found.
 745          */
 746         public function get_route_options( $route ) {
 747                 if ( ! isset( $this->route_options[ $route ] ) ) {
 748                         return null;
 749                 }
 750
 751                 return $this->route_options[ $route ];
 752         }
 753
 754         /**
 755          * Matches the request to a callback and call it.
 756          *
 757          * @since 4.4.0
 758          * @access public
 759          *
 760          * @param WP_REST_Request $request Request to attempt dispatching.
 761          * @return WP_REST_Response Response returned by the callback.
 762          */
 763         public function dispatch( $request ) {
 764                 /**
 765                  * Filter the pre-calculated result of a REST dispatch request.
 766                  *
 767                  * Allow hijacking the request before dispatching by returning a non-empty. The returned value
 768                  * will be used to serve the request instead.
 769                  *
 770                  * @since 4.4.0
 771                  *
 772                  * @param mixed           $result  Response to replace the requested version with. Can be anything
 773                  *                                 a normal endpoint can return, or null to not hijack the request.
 774                  * @param WP_REST_Server  $this    Server instance.
 775                  * @param WP_REST_Request $request Request used to generate the response.
 776                  */
 777                 $result = apply_filters( 'rest_pre_dispatch', null, $this, $request );
 778
 779                 if ( ! empty( $result ) ) {
 780                         return $result;
 781                 }
 782
 783                 $method = $request->get_method();
 784                 $path   = $request->get_route();
 785
 786                 foreach ( $this->get_routes() as $route => $handlers ) {
 787                         $match = preg_match( '@^' . $route . '$@i', $path, $args );
 788
 789                         if ( ! $match ) {
 790                                 continue;
 791                         }
 792
 793                         foreach ( $handlers as $handler ) {
 794                                 $callback  = $handler['callback'];
 795                                 $response = null;
 796
 797                                 $checked_method = 'HEAD' === $method ? 'GET' : $method;
 798                                 if ( empty( $handler['methods'][ $checked_method ] ) ) {
 799                                         continue;
 800                                 }
 801
 802                                 if ( ! is_callable( $callback ) ) {
 803                                         $response = new WP_Error( 'rest_invalid_handler', __( 'The handler for the route is invalid' ), array( 'status' => 500 ) );
 804                                 }
 805
 806                                 if ( ! is_wp_error( $response ) ) {
 807                                         // Remove the redundant preg_match argument.
 808                                         unset( $args[0] );
 809
 810                                         $request->set_url_params( $args );
 811                                         $request->set_attributes( $handler );
 812
 813                                         $request->sanitize_params();
 814
 815                                         $defaults = array();
 816
 817                                         foreach ( $handler['args'] as $arg => $options ) {
 818                                                 if ( isset( $options['default'] ) ) {
 819                                                         $defaults[ $arg ] = $options['default'];
 820                                                 }
 821                                         }
 822
 823                                         $request->set_default_params( $defaults );
 824
 825                                         $check_required = $request->has_valid_params();
 826                                         if ( is_wp_error( $check_required ) ) {
 827                                                 $response = $check_required;
 828                                         }
 829                                 }
 830
 831                                 if ( ! is_wp_error( $response ) ) {
 832                                         // Check permission specified on the route.
 833                                         if ( ! empty( $handler['permission_callback'] ) ) {
 834                                                 $permission = call_user_func( $handler['permission_callback'], $request );
 835
 836                                                 if ( is_wp_error( $permission ) ) {
 837                                                         $response = $permission;
 838                                                 } else if ( false === $permission || null === $permission ) {
 839                                                         $response = new WP_Error( 'rest_forbidden', __( "You don't have permission to do this." ), array( 'status' => 403 ) );
 840                                                 }
 841                                         }
 842                                 }
 843
 844                                 if ( ! is_wp_error( $response ) ) {
 845                                         /**
 846                                          * Filter the REST dispatch request result.
 847                                          *
 848                                          * Allow plugins to override dispatching the request.
 849                                          *
 850                                          * @since 4.4.0
 851                                          *
 852                                          * @param bool            $dispatch_result Dispatch result, will be used if not empty.
 853                                          * @param WP_REST_Request $request         Request used to generate the response.
 854                                          */
 855                                         $dispatch_result = apply_filters( 'rest_dispatch_request', null, $request );
 856
 857                                         // Allow plugins to halt the request via this filter.
 858                                         if ( null !== $dispatch_result ) {
 859                                                 $response = $dispatch_result;
 860                                         } else {
 861                                                 $response = call_user_func( $callback, $request );
 862                                         }
 863                                 }
 864
 865                                 if ( is_wp_error( $response ) ) {
 866                                         $response = $this->error_to_response( $response );
 867                                 } else {
 868                                         $response = rest_ensure_response( $response );
 869                                 }
 870
 871                                 $response->set_matched_route( $route );
 872                                 $response->set_matched_handler( $handler );
 873
 874                                 return $response;
 875                         }
 876                 }
 877
 878                 return $this->error_to_response( new WP_Error( 'rest_no_route', __( 'No route was found matching the URL and request method' ), array( 'status' => 404 ) ) );
 879         }
 880
 881         /**
 882          * Returns if an error occurred during most recent JSON encode/decode.
 883          *
 884          * Strings to be translated will be in format like
 885          * "Encoding error: Maximum stack depth exceeded".
 886          *
 887          * @since 4.4.0
 888          * @access protected
 889          *
 890          * @return bool|string Boolean false or string error message.
 891          */
 892         protected function get_json_last_error() {
 893                 // See https://core.trac.wordpress.org/ticket/27799.
 894                 if ( ! function_exists( 'json_last_error' ) ) {
 895                         return false;
 896                 }
 897
 898                 $last_error_code = json_last_error();
 899
 900                 if ( ( defined( 'JSON_ERROR_NONE' ) && JSON_ERROR_NONE === $last_error_code ) || empty( $last_error_code ) ) {
 901                         return false;
 902                 }
 903
 904                 return json_last_error_msg();
 905         }
 906
 907         /**
 908          * Retrieves the site index.
 909          *
 910          * This endpoint describes the capabilities of the site.
 911          *
 912          * @since 4.4.0
 913          * @access public
 914          *
 915          * @param array $request {
 916          *     Request.
 917          *
 918          *     @type string $context Context.
 919          * }
 920          * @return array Index entity
 921          */
 922         public function get_index( $request ) {
 923                 // General site data.
 924                 $available = array(
 925                         'name'           => get_option( 'blogname' ),
 926                         'description'    => get_option( 'blogdescription' ),
 927                         'url'            => get_option( 'siteurl' ),
 928                         'namespaces'     => array_keys( $this->namespaces ),
 929                         'authentication' => array(),
 930                         'routes'         => $this->get_data_for_routes( $this->get_routes(), $request['context'] ),
 931                 );
 932
 933                 $response = new WP_REST_Response( $available );
 934
 935                 $response->add_link( 'help', 'http://v2.wp-api.org/' );
 936
 937                 /**
 938                  * Filter the API root index data.
 939                  *
 940                  * This contains the data describing the API. This includes information
 941                  * about supported authentication schemes, supported namespaces, routes
 942                  * available on the API, and a small amount of data about the site.
 943                  *
 944                  * @since 4.4.0
 945                  *
 946                  * @param WP_REST_Response $response Response data.
 947                  */
 948                 return apply_filters( 'rest_index', $response );
 949         }
 950
 951         /**
 952          * Retrieves the index for a namespace.
 953          *
 954          * @since 4.4.0
 955          * @access public
 956          *
 957          * @param WP_REST_Request $request REST request instance.
 958          * @return WP_REST_Response|WP_Error WP_REST_Response instance if the index was found,
 959          *                                   WP_Error if the namespace isn't set.
 960          */
 961         public function get_namespace_index( $request ) {
 962                 $namespace = $request['namespace'];
 963
 964                 if ( ! isset( $this->namespaces[ $namespace ] ) ) {
 965                         return new WP_Error( 'rest_invalid_namespace', __( 'The specified namespace could not be found.' ), array( 'status' => 404 ) );
 966                 }
 967
 968                 $routes = $this->namespaces[ $namespace ];
 969                 $endpoints = array_intersect_key( $this->get_routes(), $routes );
 970
 971                 $data = array(
 972                         'namespace' => $namespace,
 973                         'routes' => $this->get_data_for_routes( $endpoints, $request['context'] ),
 974                 );
 975                 $response = rest_ensure_response( $data );
 976
 977                 // Link to the root index.
 978                 $response->add_link( 'up', rest_url( '/' ) );
 979
 980                 /**
 981                  * Filter the namespace index data.
 982                  *
 983                  * This typically is just the route data for the namespace, but you can
 984                  * add any data you'd like here.
 985                  *
 986                  * @since 4.4.0
 987                  *
 988                  * @param WP_REST_Response $response Response data.
 989                  * @param WP_REST_Request  $request  Request data. The namespace is passed as the 'namespace' parameter.
 990                  */
 991                 return apply_filters( 'rest_namespace_index', $response, $request );
 992         }
 993
 994         /**
 995          * Retrieves the publicly-visible data for routes.
 996          *
 997          * @since 4.4.0
 998          * @access public
 999          *
1000          * @param array  $routes  Routes to get data for.
1001          * @param string $context Optional. Context for data. Accepts 'view' or 'help'. Default 'view'.
1002          * @return array Route data to expose in indexes.
1003          */
1004         public function get_data_for_routes( $routes, $context = 'view' ) {
1005                 $available = array();
1006
1007                 // Find the available routes.
1008                 foreach ( $routes as $route => $callbacks ) {
1009                         $data = $this->get_data_for_route( $route, $callbacks, $context );
1010                         if ( empty( $data ) ) {
1011                                 continue;
1012                         }
1013
1014                         /**
1015                          * Filter the REST endpoint data.
1016                          *
1017                          * @since 4.4.0
1018                          *
1019                          * @param WP_REST_Request $request Request data. The namespace is passed as the 'namespace' parameter.
1020                          */
1021                         $available[ $route ] = apply_filters( 'rest_endpoints_description', $data );
1022                 }
1023
1024                 /**
1025                  * Filter the publicly-visible data for routes.
1026                  *
1027                  * This data is exposed on indexes and can be used by clients or
1028                  * developers to investigate the site and find out how to use it. It
1029                  * acts as a form of self-documentation.
1030                  *
1031                  * @since 4.4.0
1032                  *
1033                  * @param array $available Map of route to route data.
1034                  * @param array $routes    Internal route data as an associative array.
1035                  */
1036                 return apply_filters( 'rest_route_data', $available, $routes );
1037         }
1038
1039         /**
1040          * Retrieves publicly-visible data for the route.
1041          *
1042          * @since 4.4.0
1043          * @access public
1044          *
1045          * @param string $route     Route to get data for.
1046          * @param array  $callbacks Callbacks to convert to data.
1047          * @param string $context   Optional. Context for the data. Accepts 'view' or 'help'. Default 'view'.
1048          * @return array|null Data for the route, or null if no publicly-visible data.
1049          */
1050         public function get_data_for_route( $route, $callbacks, $context = 'view' ) {
1051                 $data = array(
1052                         'namespace' => '',
1053                         'methods' => array(),
1054                         'endpoints' => array(),
1055                 );
1056
1057                 if ( isset( $this->route_options[ $route ] ) ) {
1058                         $options = $this->route_options[ $route ];
1059
1060                         if ( isset( $options['namespace'] ) ) {
1061                                 $data['namespace'] = $options['namespace'];
1062                         }
1063
1064                         if ( isset( $options['schema'] ) && 'help' === $context ) {
1065                                 $data['schema'] = call_user_func( $options['schema'] );
1066                         }
1067                 }
1068
1069                 $route = preg_replace( '#\(\?P<(\w+?)>.*?\)#', '{$1}', $route );
1070
1071                 foreach ( $callbacks as $callback ) {
1072                         // Skip to the next route if any callback is hidden.
1073                         if ( empty( $callback['show_in_index'] ) ) {
1074                                 continue;
1075                         }
1076
1077                         $data['methods'] = array_merge( $data['methods'], array_keys( $callback['methods'] ) );
1078                         $endpoint_data = array(
1079                                 'methods' => array_keys( $callback['methods'] ),
1080                         );
1081
1082                         if ( isset( $callback['args'] ) ) {
1083                                 $endpoint_data['args'] = array();
1084                                 foreach ( $callback['args'] as $key => $opts ) {
1085                                         $arg_data = array(
1086                                                 'required' => ! empty( $opts['required'] ),
1087                                         );
1088                                         if ( isset( $opts['default'] ) ) {
1089                                                 $arg_data['default'] = $opts['default'];
1090                                         }
1091                                         if ( isset( $opts['enum'] ) ) {
1092                                                 $arg_data['enum'] = $opts['enum'];
1093                                         }
1094                                         if ( isset( $opts['description'] ) ) {
1095                                                 $arg_data['description'] = $opts['description'];
1096                                         }
1097                                         $endpoint_data['args'][ $key ] = $arg_data;
1098                                 }
1099                         }
1100
1101                         $data['endpoints'][] = $endpoint_data;
1102
1103                         // For non-variable routes, generate links.
1104                         if ( strpos( $route, '{' ) === false ) {
1105                                 $data['_links'] = array(
1106                                         'self' => rest_url( $route ),
1107                                 );
1108                         }
1109                 }
1110
1111                 if ( empty( $data['methods'] ) ) {
1112                         // No methods supported, hide the route.
1113                         return null;
1114                 }
1115
1116                 return $data;
1117         }
1118
1119         /**
1120          * Sends an HTTP status code.
1121          *
1122          * @since 4.4.0
1123          * @access protected
1124          *
1125          * @param int $code HTTP status.
1126          */
1127         protected function set_status( $code ) {
1128                 status_header( $code );
1129         }
1130
1131         /**
1132          * Sends an HTTP header.
1133          *
1134          * @since 4.4.0
1135          * @access public
1136          *
1137          * @param string $key Header key.
1138          * @param string $value Header value.
1139          */
1140         public function send_header( $key, $value ) {
1141                 /*
1142                  * Sanitize as per RFC2616 (Section 4.2):
1143                  *
1144                  * Any LWS that occurs between field-content MAY be replaced with a
1145                  * single SP before interpreting the field value or forwarding the
1146                  * message downstream.
1147                  */
1148                 $value = preg_replace( '/\s+/', ' ', $value );
1149                 header( sprintf( '%s: %s', $key, $value ) );
1150         }
1151
1152         /**
1153          * Sends multiple HTTP headers.
1154          *
1155          * @since 4.4.0
1156          * @access public
1157          *
1158          * @param array $headers Map of header name to header value.
1159          */
1160         public function send_headers( $headers ) {
1161                 foreach ( $headers as $key => $value ) {
1162                         $this->send_header( $key, $value );
1163                 }
1164         }
1165
1166         /**
1167          * Retrieves the raw request entity (body).
1168          *
1169          * @since 4.4.0
1170          * @access public
1171          *
1172          * @global string $HTTP_RAW_POST_DATA Raw post data.
1173          *
1174          * @return string Raw request data.
1175          */
1176         public static function get_raw_data() {
1177                 global $HTTP_RAW_POST_DATA;
1178
1179                 /*
1180                  * A bug in PHP < 5.2.2 makes $HTTP_RAW_POST_DATA not set by default,
1181                  * but we can do it ourself.
1182                  */
1183                 if ( ! isset( $HTTP_RAW_POST_DATA ) ) {
1184                         $HTTP_RAW_POST_DATA = file_get_contents( 'php://input' );
1185                 }
1186
1187                 return $HTTP_RAW_POST_DATA;
1188         }
1189
1190         /**
1191          * Extracts headers from a PHP-style $_SERVER array.
1192          *
1193          * @since 4.4.0
1194          * @access public
1195          *
1196          * @param array $server Associative array similar to `$_SERVER`.
1197          * @return array Headers extracted from the input.
1198          */
1199         public function get_headers( $server ) {
1200                 $headers = array();
1201
1202                 // CONTENT_* headers are not prefixed with HTTP_.
1203                 $additional = array( 'CONTENT_LENGTH' => true, 'CONTENT_MD5' => true, 'CONTENT_TYPE' => true );
1204
1205                 foreach ( $server as $key => $value ) {
1206                         if ( strpos( $key, 'HTTP_' ) === 0 ) {
1207                                 $headers[ substr( $key, 5 ) ] = $value;
1208                         } elseif ( isset( $additional[ $key ] ) ) {
1209                                 $headers[ $key ] = $value;
1210                         }
1211                 }
1212
1213                 return $headers;
1214         }
1215 }