| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * REST API functions. 4 * 5 * @package WordPress 6 * @subpackage REST_API 7 * @since 4.4.0 8 */ 9 10 /** 11 * Version number for our API. 12 * 13 * @var string 14 */ 15 define( 'REST_API_VERSION', '2.0' ); 16 17 /** 18 * Registers a REST API route. 19 * 20 * Note: Do not use before the {@see 'rest_api_init'} hook. 21 * 22 * @since 4.4.0 23 * @since 5.1.0 Added a _doing_it_wrong() notice when not called on or after the rest_api_init hook. 24 * 25 * @param string $namespace The first URL segment after core prefix. Should be unique to your package/plugin. 26 * @param string $route The base URL for route you are adding. 27 * @param array $args Optional. Either an array of options for the endpoint, or an array of arrays for 28 * multiple methods. Default empty array. 29 * @param bool $override Optional. If the route already exists, should we override it? True overrides, 30 * false merges (with newer overriding if duplicate keys exist). Default false. 31 * @return bool True on success, false on error. 32 */ 33 function register_rest_route( $namespace, $route, $args = array(), $override = false ) { 34 if ( empty( $namespace ) ) { 35 /* 36 * Non-namespaced routes are not allowed, with the exception of the main 37 * and namespace indexes. If you really need to register a 38 * non-namespaced route, call `WP_REST_Server::register_route` directly. 39 */ 40 _doing_it_wrong( 'register_rest_route', __( 'Routes must be namespaced with plugin or theme name and version.' ), '4.4.0' ); 41 return false; 42 } elseif ( empty( $route ) ) { 43 _doing_it_wrong( 'register_rest_route', __( 'Route must be specified.' ), '4.4.0' ); 44 return false; 45 } 46 47 if ( ! did_action( 'rest_api_init' ) ) { 48 _doing_it_wrong( 49 'register_rest_route', 50 sprintf( 51 /* translators: %s: rest_api_init */ 52 __( 'REST API routes must be registered on the %s action.' ), 53 '<code>rest_api_init</code>' 54 ), 55 '5.1.0' 56 ); 57 } 58 59 if ( isset( $args['args'] ) ) { 60 $common_args = $args['args']; 61 unset( $args['args'] ); 62 } else { 63 $common_args = array(); 64 } 65 66 if ( isset( $args['callback'] ) ) { 67 // Upgrade a single set to multiple. 68 $args = array( $args ); 69 } 70 71 $defaults = array( 72 'methods' => 'GET', 73 'callback' => null, 74 'args' => array(), 75 ); 76 foreach ( $args as $key => &$arg_group ) { 77 if ( ! is_numeric( $key ) ) { 78 // Route option, skip here. 79 continue; 80 } 81 82 $arg_group = array_merge( $defaults, $arg_group ); 83 $arg_group['args'] = array_merge( $common_args, $arg_group['args'] ); 84 } 85 86 $full_route = '/' . trim( $namespace, '/' ) . '/' . trim( $route, '/' ); 87 rest_get_server()->register_route( $namespace, $full_route, $args, $override ); 88 return true; 89 } 90 91 /** 92 * Registers a new field on an existing WordPress object type. 93 * 94 * @since 4.7.0 95 * 96 * @global array $wp_rest_additional_fields Holds registered fields, organized 97 * by object type. 98 * 99 * @param string|array $object_type Object(s) the field is being registered 100 * to, "post"|"term"|"comment" etc. 101 * @param string $attribute The attribute name. 102 * @param array $args { 103 * Optional. An array of arguments used to handle the registered field. 104 * 105 * @type callable|null $get_callback Optional. The callback function used to retrieve the field value. Default is 106 * 'null', the field will not be returned in the response. The function will 107 * be passed the prepared object data. 108 * @type callable|null $update_callback Optional. The callback function used to set and update the field value. Default 109 * is 'null', the value cannot be set or updated. The function will be passed 110 * the model object, like WP_Post. 111 * @type array|null $schema Optional. The callback function used to create the schema for this field. 112 * Default is 'null', no schema entry will be returned. 113 * } 114 */ 115 function register_rest_field( $object_type, $attribute, $args = array() ) { 116 $defaults = array( 117 'get_callback' => null, 118 'update_callback' => null, 119 'schema' => null, 120 ); 121 122 $args = wp_parse_args( $args, $defaults ); 123 124 global $wp_rest_additional_fields; 125 126 $object_types = (array) $object_type; 127 128 foreach ( $object_types as $object_type ) { 129 $wp_rest_additional_fields[ $object_type ][ $attribute ] = $args; 130 } 131 } 132 133 /** 134 * Registers rewrite rules for the API. 135 * 136 * @since 4.4.0 137 * 138 * @see rest_api_register_rewrites() 139 * @global WP $wp Current WordPress environment instance. 140 */ 141 function rest_api_init() { 142 rest_api_register_rewrites(); 143 144 global $wp; 145 $wp->add_query_var( 'rest_route' ); 146 } 147 148 /** 149 * Adds REST rewrite rules. 150 * 151 * @since 4.4.0 152 * 153 * @see add_rewrite_rule() 154 * @global WP_Rewrite $wp_rewrite WordPress rewrite component. 155 */ 156 function rest_api_register_rewrites() { 157 global $wp_rewrite; 158 159 add_rewrite_rule( '^' . rest_get_url_prefix() . '/?$', 'index.php?rest_route=/', 'top' ); 160 add_rewrite_rule( '^' . rest_get_url_prefix() . '/(.*)?', 'index.php?rest_route=/$matches[1]', 'top' ); 161 add_rewrite_rule( '^' . $wp_rewrite->index . '/' . rest_get_url_prefix() . '/?$', 'index.php?rest_route=/', 'top' ); 162 add_rewrite_rule( '^' . $wp_rewrite->index . '/' . rest_get_url_prefix() . '/(.*)?', 'index.php?rest_route=/$matches[1]', 'top' ); 163 } 164 165 /** 166 * Registers the default REST API filters. 167 * 168 * Attached to the {@see 'rest_api_init'} action 169 * to make testing and disabling these filters easier. 170 * 171 * @since 4.4.0 172 */ 173 function rest_api_default_filters() { 174 // Deprecated reporting. 175 add_action( 'deprecated_function_run', 'rest_handle_deprecated_function', 10, 3 ); 176 add_filter( 'deprecated_function_trigger_error', '__return_false' ); 177 add_action( 'deprecated_argument_run', 'rest_handle_deprecated_argument', 10, 3 ); 178 add_filter( 'deprecated_argument_trigger_error', '__return_false' ); 179 180 // Default serving. 181 add_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' ); 182 add_filter( 'rest_post_dispatch', 'rest_send_allow_header', 10, 3 ); 183 add_filter( 'rest_post_dispatch', 'rest_filter_response_fields', 10, 3 ); 184 185 add_filter( 'rest_pre_dispatch', 'rest_handle_options_request', 10, 3 ); 186 } 187 188 /** 189 * Registers default REST API routes. 190 * 191 * @since 4.7.0 192 */ 193 function create_initial_rest_routes() { 194 foreach ( get_post_types( array( 'show_in_rest' => true ), 'objects' ) as $post_type ) { 195 $controller = $post_type->get_rest_controller(); 196 197 if ( ! $controller ) { 198 continue; 199 } 200 201 $controller->register_routes(); 202 203 if ( post_type_supports( $post_type->name, 'revisions' ) ) { 204 $revisions_controller = new WP_REST_Revisions_Controller( $post_type->name ); 205 $revisions_controller->register_routes(); 206 } 207 208 if ( 'attachment' !== $post_type->name ) { 209 $autosaves_controller = new WP_REST_Autosaves_Controller( $post_type->name ); 210 $autosaves_controller->register_routes(); 211 } 212 } 213 214 // Post types. 215 $controller = new WP_REST_Post_Types_Controller; 216 $controller->register_routes(); 217 218 // Post statuses. 219 $controller = new WP_REST_Post_Statuses_Controller; 220 $controller->register_routes(); 221 222 // Taxonomies. 223 $controller = new WP_REST_Taxonomies_Controller; 224 $controller->register_routes(); 225 226 // Terms. 227 foreach ( get_taxonomies( array( 'show_in_rest' => true ), 'object' ) as $taxonomy ) { 228 $class = ! empty( $taxonomy->rest_controller_class ) ? $taxonomy->rest_controller_class : 'WP_REST_Terms_Controller'; 229 230 if ( ! class_exists( $class ) ) { 231 continue; 232 } 233 $controller = new $class( $taxonomy->name ); 234 if ( ! is_subclass_of( $controller, 'WP_REST_Controller' ) ) { 235 continue; 236 } 237 238 $controller->register_routes(); 239 } 240 241 // Users. 242 $controller = new WP_REST_Users_Controller; 243 $controller->register_routes(); 244 245 // Comments. 246 $controller = new WP_REST_Comments_Controller; 247 $controller->register_routes(); 248 249 /** 250 * Filters the search handlers to use in the REST search controller. 251 * 252 * @since 5.0.0 253 * 254 * @param array $search_handlers List of search handlers to use in the controller. Each search 255 * handler instance must extend the `WP_REST_Search_Handler` class. 256 * Default is only a handler for posts. 257 */ 258 $search_handlers = apply_filters( 'wp_rest_search_handlers', array( new WP_REST_Post_Search_Handler() ) ); 259 260 $controller = new WP_REST_Search_Controller( $search_handlers ); 261 $controller->register_routes(); 262 263 // Block Renderer. 264 $controller = new WP_REST_Block_Renderer_Controller; 265 $controller->register_routes(); 266 267 // Settings. 268 $controller = new WP_REST_Settings_Controller; 269 $controller->register_routes(); 270 271 // Themes. 272 $controller = new WP_REST_Themes_Controller; 273 $controller->register_routes(); 274 275 } 276 277 /** 278 * Loads the REST API. 279 * 280 * @since 4.4.0 281 * 282 * @global WP $wp Current WordPress environment instance. 283 */ 284 function rest_api_loaded() { 285 if ( empty( $GLOBALS['wp']->query_vars['rest_route'] ) ) { 286 return; 287 } 288 289 /** 290 * Whether this is a REST Request. 291 * 292 * @since 4.4.0 293 * @var bool 294 */ 295 define( 'REST_REQUEST', true ); 296 297 // Initialize the server. 298 $server = rest_get_server(); 299 300 // Fire off the request. 301 $route = untrailingslashit( $GLOBALS['wp']->query_vars['rest_route'] ); 302 if ( empty( $route ) ) { 303 $route = '/'; 304 } 305 $server->serve_request( $route ); 306 307 // We're done. 308 die(); 309 } 310 311 /** 312 * Retrieves the URL prefix for any API resource. 313 * 314 * @since 4.4.0 315 * 316 * @return string Prefix. 317 */ 318 function rest_get_url_prefix() { 319 /** 320 * Filters the REST URL prefix. 321 * 322 * @since 4.4.0 323 * 324 * @param string $prefix URL prefix. Default 'wp-json'. 325 */ 326 return apply_filters( 'rest_url_prefix', 'wp-json' ); 327 } 328 329 /** 330 * Retrieves the URL to a REST endpoint on a site. 331 * 332 * Note: The returned URL is NOT escaped. 333 * 334 * @since 4.4.0 335 * 336 * @todo Check if this is even necessary 337 * @global WP_Rewrite $wp_rewrite WordPress rewrite component. 338 * 339 * @param int $blog_id Optional. Blog ID. Default of null returns URL for current blog. 340 * @param string $path Optional. REST route. Default '/'. 341 * @param string $scheme Optional. Sanitization scheme. Default 'rest'. 342 * @return string Full URL to the endpoint. 343 */ 344 function get_rest_url( $blog_id = null, $path = '/', $scheme = 'rest' ) { 345 if ( empty( $path ) ) { 346 $path = '/'; 347 } 348 349 $path = '/' . ltrim( $path, '/' ); 350 351 if ( is_multisite() && get_blog_option( $blog_id, 'permalink_structure' ) || get_option( 'permalink_structure' ) ) { 352 global $wp_rewrite; 353 354 if ( $wp_rewrite->using_index_permalinks() ) { 355 $url = get_home_url( $blog_id, $wp_rewrite->index . '/' . rest_get_url_prefix(), $scheme ); 356 } else { 357 $url = get_home_url( $blog_id, rest_get_url_prefix(), $scheme ); 358 } 359 360 $url .= $path; 361 } else { 362 $url = trailingslashit( get_home_url( $blog_id, '', $scheme ) ); 363 // nginx only allows HTTP/1.0 methods when redirecting from / to /index.php 364 // To work around this, we manually add index.php to the URL, avoiding the redirect. 365 if ( 'index.php' !== substr( $url, 9 ) ) { 366 $url .= 'index.php'; 367 } 368 369 $url = add_query_arg( 'rest_route', $path, $url ); 370 } 371 372 if ( is_ssl() && isset( $_SERVER['SERVER_NAME'] ) ) { 373 // If the current host is the same as the REST URL host, force the REST URL scheme to HTTPS. 374 if ( $_SERVER['SERVER_NAME'] === parse_url( get_home_url( $blog_id ), PHP_URL_HOST ) ) { 375 $url = set_url_scheme( $url, 'https' ); 376 } 377 } 378 379 if ( is_admin() && force_ssl_admin() ) { 380 // In this situation the home URL may be http:, and `is_ssl()` may be 381 // false, but the admin is served over https: (one way or another), so 382 // REST API usage will be blocked by browsers unless it is also served 383 // over HTTPS. 384 $url = set_url_scheme( $url, 'https' ); 385 } 386 387 /** 388 * Filters the REST URL. 389 * 390 * Use this filter to adjust the url returned by the get_rest_url() function. 391 * 392 * @since 4.4.0 393 * 394 * @param string $url REST URL. 395 * @param string $path REST route. 396 * @param int $blog_id Blog ID. 397 * @param string $scheme Sanitization scheme. 398 */ 399 return apply_filters( 'rest_url', $url, $path, $blog_id, $scheme ); 400 } 401 402 /** 403 * Retrieves the URL to a REST endpoint. 404 * 405 * Note: The returned URL is NOT escaped. 406 * 407 * @since 4.4.0 408 * 409 * @param string $path Optional. REST route. Default empty. 410 * @param string $scheme Optional. Sanitization scheme. Default 'rest'. 411 * @return string Full URL to the endpoint. 412 */ 413 function rest_url( $path = '', $scheme = 'rest' ) { 414 return get_rest_url( null, $path, $scheme ); 415 } 416 417 /** 418 * Do a REST request. 419 * 420 * Used primarily to route internal requests through WP_REST_Server. 421 * 422 * @since 4.4.0 423 * 424 * @param WP_REST_Request|string $request Request. 425 * @return WP_REST_Response REST response. 426 */ 427 function rest_do_request( $request ) { 428 $request = rest_ensure_request( $request ); 429 return rest_get_server()->dispatch( $request ); 430 } 431 432 /** 433 * Retrieves the current REST server instance. 434 * 435 * Instantiates a new instance if none exists already. 436 * 437 * @since 4.5.0 438 * 439 * @global WP_REST_Server $wp_rest_server REST server instance. 440 * 441 * @return WP_REST_Server REST server instance. 442 */ 443 function rest_get_server() { 444 /* @var WP_REST_Server $wp_rest_server */ 445 global $wp_rest_server; 446 447 if ( empty( $wp_rest_server ) ) { 448 /** 449 * Filters the REST Server Class. 450 * 451 * This filter allows you to adjust the server class used by the API, using a 452 * different class to handle requests. 453 * 454 * @since 4.4.0 455 * 456 * @param string $class_name The name of the server class. Default 'WP_REST_Server'. 457 */ 458 $wp_rest_server_class = apply_filters( 'wp_rest_server_class', 'WP_REST_Server' ); 459 $wp_rest_server = new $wp_rest_server_class; 460 461 /** 462 * Fires when preparing to serve an API request. 463 * 464 * Endpoint objects should be created and register their hooks on this action rather 465 * than another action to ensure they're only loaded when needed. 466 * 467 * @since 4.4.0 468 * 469 * @param WP_REST_Server $wp_rest_server Server object. 470 */ 471 do_action( 'rest_api_init', $wp_rest_server ); 472 } 473 474 return $wp_rest_server; 475 } 476 477 /** 478 * Ensures request arguments are a request object (for consistency). 479 * 480 * @since 4.4.0 481 * @since 5.3.0 Accept string argument for the request path. 482 * 483 * @param array|string|WP_REST_Request $request Request to check. 484 * @return WP_REST_Request REST request instance. 485 */ 486 function rest_ensure_request( $request ) { 487 if ( $request instanceof WP_REST_Request ) { 488 return $request; 489 } 490 491 if ( is_string( $request ) ) { 492 return new WP_REST_Request( 'GET', $request ); 493 } 494 495 return new WP_REST_Request( 'GET', '', $request ); 496 } 497 498 /** 499 * Ensures a REST response is a response object (for consistency). 500 * 501 * This implements WP_HTTP_Response, allowing usage of `set_status`/`header`/etc 502 * without needing to double-check the object. Will also allow WP_Error to indicate error 503 * responses, so users should immediately check for this value. 504 * 505 * @since 4.4.0 506 * 507 * @param WP_HTTP_Response|WP_Error|mixed $response Response to check. 508 * @return WP_REST_Response|mixed If response generated an error, WP_Error, if response 509 * is already an instance, WP_HTTP_Response, otherwise 510 * returns a new WP_REST_Response instance. 511 */ 512 function rest_ensure_response( $response ) { 513 if ( is_wp_error( $response ) ) { 514 return $response; 515 } 516 517 if ( $response instanceof WP_HTTP_Response ) { 518 return $response; 519 } 520 521 return new WP_REST_Response( $response ); 522 } 523 524 /** 525 * Handles _deprecated_function() errors. 526 * 527 * @since 4.4.0 528 * 529 * @param string $function The function that was called. 530 * @param string $replacement The function that should have been called. 531 * @param string $version Version. 532 */ 533 function rest_handle_deprecated_function( $function, $replacement, $version ) { 534 if ( ! WP_DEBUG || headers_sent() ) { 535 return; 536 } 537 if ( ! empty( $replacement ) ) { 538 /* translators: 1: Function name, 2: WordPress version number, 3: New function name. */ 539 $string = sprintf( __( '%1$s (since %2$s; use %3$s instead)' ), $function, $version, $replacement ); 540 } else { 541 /* translators: 1: Function name, 2: WordPress version number. */ 542 $string = sprintf( __( '%1$s (since %2$s; no alternative available)' ), $function, $version ); 543 } 544 545 header( sprintf( 'X-WP-DeprecatedFunction: %s', $string ) ); 546 } 547 548 /** 549 * Handles _deprecated_argument() errors. 550 * 551 * @since 4.4.0 552 * 553 * @param string $function The function that was called. 554 * @param string $message A message regarding the change. 555 * @param string $version Version. 556 */ 557 function rest_handle_deprecated_argument( $function, $message, $version ) { 558 if ( ! WP_DEBUG || headers_sent() ) { 559 return; 560 } 561 if ( ! empty( $message ) ) { 562 /* translators: 1: Function name, 2: WordPress version number, 3: Error message. */ 563 $string = sprintf( __( '%1$s (since %2$s; %3$s)' ), $function, $version, $message ); 564 } else { 565 /* translators: 1: Function name, 2: WordPress version number. */ 566 $string = sprintf( __( '%1$s (since %2$s; no alternative available)' ), $function, $version ); 567 } 568 569 header( sprintf( 'X-WP-DeprecatedParam: %s', $string ) ); 570 } 571 572 /** 573 * Sends Cross-Origin Resource Sharing headers with API requests. 574 * 575 * @since 4.4.0 576 * 577 * @param mixed $value Response data. 578 * @return mixed Response data. 579 */ 580 function rest_send_cors_headers( $value ) { 581 $origin = get_http_origin(); 582 583 if ( $origin ) { 584 // Requests from file:// and data: URLs send "Origin: null" 585 if ( 'null' !== $origin ) { 586 $origin = esc_url_raw( $origin ); 587 } 588 header( 'Access-Control-Allow-Origin: ' . $origin ); 589 header( 'Access-Control-Allow-Methods: OPTIONS, GET, POST, PUT, PATCH, DELETE' ); 590 header( 'Access-Control-Allow-Credentials: true' ); 591 header( 'Vary: Origin', false ); 592 } elseif ( ! headers_sent() && 'GET' === $_SERVER['REQUEST_METHOD'] && ! is_user_logged_in() ) { 593 header( 'Vary: Origin', false ); 594 } 595 596 return $value; 597 } 598 599 /** 600 * Handles OPTIONS requests for the server. 601 * 602 * This is handled outside of the server code, as it doesn't obey normal route 603 * mapping. 604 * 605 * @since 4.4.0 606 * 607 * @param mixed $response Current response, either response or `null` to indicate pass-through. 608 * @param WP_REST_Server $handler ResponseHandler instance (usually WP_REST_Server). 609 * @param WP_REST_Request $request The request that was used to make current response. 610 * @return WP_REST_Response Modified response, either response or `null` to indicate pass-through. 611 */ 612 function rest_handle_options_request( $response, $handler, $request ) { 613 if ( ! empty( $response ) || $request->get_method() !== 'OPTIONS' ) { 614 return $response; 615 } 616 617 $response = new WP_REST_Response(); 618 $data = array(); 619 620 foreach ( $handler->get_routes() as $route => $endpoints ) { 621 $match = preg_match( '@^' . $route . '$@i', $request->get_route(), $matches ); 622 623 if ( ! $match ) { 624 continue; 625 } 626 627 $args = array(); 628 foreach ( $matches as $param => $value ) { 629 if ( ! is_int( $param ) ) { 630 $args[ $param ] = $value; 631 } 632 } 633 634 foreach ( $endpoints as $endpoint ) { 635 // Remove the redundant preg_match argument. 636 unset( $args[0] ); 637 638 $request->set_url_params( $args ); 639 $request->set_attributes( $endpoint ); 640 } 641 642 $data = $handler->get_data_for_route( $route, $endpoints, 'help' ); 643 $response->set_matched_route( $route ); 644 break; 645 } 646 647 $response->set_data( $data ); 648 return $response; 649 } 650 651 /** 652 * Sends the "Allow" header to state all methods that can be sent to the current route. 653 * 654 * @since 4.4.0 655 * 656 * @param WP_REST_Response $response Current response being served. 657 * @param WP_REST_Server $server ResponseHandler instance (usually WP_REST_Server). 658 * @param WP_REST_Request $request The request that was used to make current response. 659 * @return WP_REST_Response Response to be served, with "Allow" header if route has allowed methods. 660 */ 661 function rest_send_allow_header( $response, $server, $request ) { 662 $matched_route = $response->get_matched_route(); 663 664 if ( ! $matched_route ) { 665 return $response; 666 } 667 668 $routes = $server->get_routes(); 669 670 $allowed_methods = array(); 671 672 // Get the allowed methods across the routes. 673 foreach ( $routes[ $matched_route ] as $_handler ) { 674 foreach ( $_handler['methods'] as $handler_method => $value ) { 675 676 if ( ! empty( $_handler['permission_callback'] ) ) { 677 678 $permission = call_user_func( $_handler['permission_callback'], $request ); 679 680 $allowed_methods[ $handler_method ] = true === $permission; 681 } else { 682 $allowed_methods[ $handler_method ] = true; 683 } 684 } 685 } 686 687 // Strip out all the methods that are not allowed (false values). 688 $allowed_methods = array_filter( $allowed_methods ); 689 690 if ( $allowed_methods ) { 691 $response->header( 'Allow', implode( ', ', array_map( 'strtoupper', array_keys( $allowed_methods ) ) ) ); 692 } 693 694 return $response; 695 } 696 697 /** 698 * Recursively computes the intersection of arrays using keys for comparison. 699 * 700 * @param array $array1 The array with master keys to check. 701 * @param array $array2 An array to compare keys against. 702 * 703 * @return array An associative array containing all the entries of array1 which have keys that are present in all arguments. 704 */ 705 function _rest_array_intersect_key_recursive( $array1, $array2 ) { 706 $array1 = array_intersect_key( $array1, $array2 ); 707 foreach ( $array1 as $key => $value ) { 708 if ( is_array( $value ) && is_array( $array2[ $key ] ) ) { 709 $array1[ $key ] = _rest_array_intersect_key_recursive( $value, $array2[ $key ] ); 710 } 711 } 712 return $array1; 713 } 714 715 /** 716 * Filter the API response to include only a white-listed set of response object fields. 717 * 718 * @since 4.8.0 719 * 720 * @param WP_REST_Response $response Current response being served. 721 * @param WP_REST_Server $server ResponseHandler instance (usually WP_REST_Server). 722 * @param WP_REST_Request $request The request that was used to make current response. 723 * 724 * @return WP_REST_Response Response to be served, trimmed down to contain a subset of fields. 725 */ 726 function rest_filter_response_fields( $response, $server, $request ) { 727 if ( ! isset( $request['_fields'] ) || $response->is_error() ) { 728 return $response; 729 } 730 731 $data = $response->get_data(); 732 733 $fields = wp_parse_list( $request['_fields'] ); 734 735 if ( 0 === count( $fields ) ) { 736 return $response; 737 } 738 739 // Trim off outside whitespace from the comma delimited list. 740 $fields = array_map( 'trim', $fields ); 741 742 // Create nested array of accepted field hierarchy. 743 $fields_as_keyed = array(); 744 foreach ( $fields as $field ) { 745 $parts = explode( '.', $field ); 746 $ref = &$fields_as_keyed; 747 while ( count( $parts ) > 1 ) { 748 $next = array_shift( $parts ); 749 if ( isset( $ref[ $next ] ) && true === $ref[ $next ] ) { 750 // Skip any sub-properties if their parent prop is already marked for inclusion. 751 break 2; 752 } 753 $ref[ $next ] = isset( $ref[ $next ] ) ? $ref[ $next ] : array(); 754 $ref = &$ref[ $next ]; 755 } 756 $last = array_shift( $parts ); 757 $ref[ $last ] = true; 758 } 759 760 if ( wp_is_numeric_array( $data ) ) { 761 $new_data = array(); 762 foreach ( $data as $item ) { 763 $new_data[] = _rest_array_intersect_key_recursive( $item, $fields_as_keyed ); 764 } 765 } else { 766 $new_data = _rest_array_intersect_key_recursive( $data, $fields_as_keyed ); 767 } 768 769 $response->set_data( $new_data ); 770 771 return $response; 772 } 773 774 /** 775 * Given an array of fields to include in a response, some of which may be 776 * `nested.fields`, determine whether the provided field should be included 777 * in the response body. 778 * 779 * If a parent field is passed in, the presence of any nested field within 780 * that parent will cause the method to return `true`. For example "title" 781 * will return true if any of `title`, `title.raw` or `title.rendered` is 782 * provided. 783 * 784 * @since 5.3.0 785 * 786 * @param string $field A field to test for inclusion in the response body. 787 * @param array $fields An array of string fields supported by the endpoint. 788 * @return bool Whether to include the field or not. 789 */ 790 function rest_is_field_included( $field, $fields ) { 791 if ( in_array( $field, $fields, true ) ) { 792 return true; 793 } 794 foreach ( $fields as $accepted_field ) { 795 // Check to see if $field is the parent of any item in $fields. 796 // A field "parent" should be accepted if "parent.child" is accepted. 797 if ( strpos( $accepted_field, "$field." ) === 0 ) { 798 return true; 799 } 800 // Conversely, if "parent" is accepted, all "parent.child" fields should 801 // also be accepted. 802 if ( strpos( $field, "$accepted_field." ) === 0 ) { 803 return true; 804 } 805 } 806 return false; 807 } 808 809 /** 810 * Adds the REST API URL to the WP RSD endpoint. 811 * 812 * @since 4.4.0 813 * 814 * @see get_rest_url() 815 */ 816 function rest_output_rsd() { 817 $api_root = get_rest_url(); 818 819 if ( empty( $api_root ) ) { 820 return; 821 } 822 ?> 823 <api name="WP-API" blogID="1" preferred="false" apiLink="<?php echo esc_url( $api_root ); ?>" /> 824 <?php 825 } 826 827 /** 828 * Outputs the REST API link tag into page header. 829 * 830 * @since 4.4.0 831 * 832 * @see get_rest_url() 833 */ 834 function rest_output_link_wp_head() { 835 $api_root = get_rest_url(); 836 837 if ( empty( $api_root ) ) { 838 return; 839 } 840 841 echo "<link rel='https://api.w.org/' href='" . esc_url( $api_root ) . "' />\n"; 842 } 843 844 /** 845 * Sends a Link header for the REST API. 846 * 847 * @since 4.4.0 848 */ 849 function rest_output_link_header() { 850 if ( headers_sent() ) { 851 return; 852 } 853 854 $api_root = get_rest_url(); 855 856 if ( empty( $api_root ) ) { 857 return; 858 } 859 860 header( 'Link: <' . esc_url_raw( $api_root ) . '>; rel="https://api.w.org/"', false ); 861 } 862 863 /** 864 * Checks for errors when using cookie-based authentication. 865 * 866 * WordPress' built-in cookie authentication is always active 867 * for logged in users. However, the API has to check nonces 868 * for each request to ensure users are not vulnerable to CSRF. 869 * 870 * @since 4.4.0 871 * 872 * @global mixed $wp_rest_auth_cookie 873 * 874 * @param WP_Error|mixed $result Error from another authentication handler, 875 * null if we should handle it, or another value if not. 876 * @return WP_Error|mixed|bool WP_Error if the cookie is invalid, the $result, otherwise true. 877 */ 878 function rest_cookie_check_errors( $result ) { 879 if ( ! empty( $result ) ) { 880 return $result; 881 } 882 883 global $wp_rest_auth_cookie; 884 885 /* 886 * Is cookie authentication being used? (If we get an auth 887 * error, but we're still logged in, another authentication 888 * must have been used). 889 */ 890 if ( true !== $wp_rest_auth_cookie && is_user_logged_in() ) { 891 return $result; 892 } 893 894 // Determine if there is a nonce. 895 $nonce = null; 896 897 if ( isset( $_REQUEST['_wpnonce'] ) ) { 898 $nonce = $_REQUEST['_wpnonce']; 899 } elseif ( isset( $_SERVER['HTTP_X_WP_NONCE'] ) ) { 900 $nonce = $_SERVER['HTTP_X_WP_NONCE']; 901 } 902 903 if ( null === $nonce ) { 904 // No nonce at all, so act as if it's an unauthenticated request. 905 wp_set_current_user( 0 ); 906 return true; 907 } 908 909 // Check the nonce. 910 $result = wp_verify_nonce( $nonce, 'wp_rest' ); 911 912 if ( ! $result ) { 913 return new WP_Error( 'rest_cookie_invalid_nonce', __( 'Cookie nonce is invalid' ), array( 'status' => 403 ) ); 914 } 915 916 // Send a refreshed nonce in header. 917 rest_get_server()->send_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) ); 918 919 return true; 920 } 921 922 /** 923 * Collects cookie authentication status. 924 * 925 * Collects errors from wp_validate_auth_cookie for use by rest_cookie_check_errors. 926 * 927 * @since 4.4.0 928 * 929 * @see current_action() 930 * @global mixed $wp_rest_auth_cookie 931 */ 932 function rest_cookie_collect_status() { 933 global $wp_rest_auth_cookie; 934 935 $status_type = current_action(); 936 937 if ( 'auth_cookie_valid' !== $status_type ) { 938 $wp_rest_auth_cookie = substr( $status_type, 12 ); 939 return; 940 } 941 942 $wp_rest_auth_cookie = true; 943 } 944 945 /** 946 * Parses an RFC3339 time into a Unix timestamp. 947 * 948 * @since 4.4.0 949 * 950 * @param string $date RFC3339 timestamp. 951 * @param bool $force_utc Optional. Whether to force UTC timezone instead of using 952 * the timestamp's timezone. Default false. 953 * @return int Unix timestamp. 954 */ 955 function rest_parse_date( $date, $force_utc = false ) { 956 if ( $force_utc ) { 957 $date = preg_replace( '/[+-]\d+:?\d+$/', '+00:00', $date ); 958 } 959 960 $regex = '#^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}(?::\d{2})?)?$#'; 961 962 if ( ! preg_match( $regex, $date, $matches ) ) { 963 return false; 964 } 965 966 return strtotime( $date ); 967 } 968 969 /** 970 * Parses a date into both its local and UTC equivalent, in MySQL datetime format. 971 * 972 * @since 4.4.0 973 * 974 * @see rest_parse_date() 975 * 976 * @param string $date RFC3339 timestamp. 977 * @param bool $is_utc Whether the provided date should be interpreted as UTC. Default false. 978 * @return array|null Local and UTC datetime strings, in MySQL datetime format (Y-m-d H:i:s), 979 * null on failure. 980 */ 981 function rest_get_date_with_gmt( $date, $is_utc = false ) { 982 // Whether or not the original date actually has a timezone string 983 // changes the way we need to do timezone conversion. Store this info 984 // before parsing the date, and use it later. 985 $has_timezone = preg_match( '#(Z|[+-]\d{2}(:\d{2})?)$#', $date ); 986 987 $date = rest_parse_date( $date ); 988 989 if ( empty( $date ) ) { 990 return null; 991 } 992 993 // At this point $date could either be a local date (if we were passed a 994 // *local* date without a timezone offset) or a UTC date (otherwise). 995 // Timezone conversion needs to be handled differently between these two 996 // cases. 997 if ( ! $is_utc && ! $has_timezone ) { 998 $local = gmdate( 'Y-m-d H:i:s', $date ); 999 $utc = get_gmt_from_date( $local ); 1000 } else { 1001 $utc = gmdate( 'Y-m-d H:i:s', $date ); 1002 $local = get_date_from_gmt( $utc ); 1003 } 1004 1005 return array( $local, $utc ); 1006 } 1007 1008 /** 1009 * Returns a contextual HTTP error code for authorization failure. 1010 * 1011 * @since 4.7.0 1012 * 1013 * @return integer 401 if the user is not logged in, 403 if the user is logged in. 1014 */ 1015 function rest_authorization_required_code() { 1016 return is_user_logged_in() ? 403 : 401; 1017 } 1018 1019 /** 1020 * Validate a request argument based on details registered to the route. 1021 * 1022 * @since 4.7.0 1023 * 1024 * @param mixed $value 1025 * @param WP_REST_Request $request 1026 * @param string $param 1027 * @return true|WP_Error 1028 */ 1029 function rest_validate_request_arg( $value, $request, $param ) { 1030 $attributes = $request->get_attributes(); 1031 if ( ! isset( $attributes['args'][ $param ] ) || ! is_array( $attributes['args'][ $param ] ) ) { 1032 return true; 1033 } 1034 $args = $attributes['args'][ $param ]; 1035 1036 return rest_validate_value_from_schema( $value, $args, $param ); 1037 } 1038 1039 /** 1040 * Sanitize a request argument based on details registered to the route. 1041 * 1042 * @since 4.7.0 1043 * 1044 * @param mixed $value 1045 * @param WP_REST_Request $request 1046 * @param string $param 1047 * @return mixed 1048 */ 1049 function rest_sanitize_request_arg( $value, $request, $param ) { 1050 $attributes = $request->get_attributes(); 1051 if ( ! isset( $attributes['args'][ $param ] ) || ! is_array( $attributes['args'][ $param ] ) ) { 1052 return $value; 1053 } 1054 $args = $attributes['args'][ $param ]; 1055 1056 return rest_sanitize_value_from_schema( $value, $args ); 1057 } 1058 1059 /** 1060 * Parse a request argument based on details registered to the route. 1061 * 1062 * Runs a validation check and sanitizes the value, primarily to be used via 1063 * the `sanitize_callback` arguments in the endpoint args registration. 1064 * 1065 * @since 4.7.0 1066 * 1067 * @param mixed $value 1068 * @param WP_REST_Request $request 1069 * @param string $param 1070 * @return mixed 1071 */ 1072 function rest_parse_request_arg( $value, $request, $param ) { 1073 $is_valid = rest_validate_request_arg( $value, $request, $param ); 1074 1075 if ( is_wp_error( $is_valid ) ) { 1076 return $is_valid; 1077 } 1078 1079 $value = rest_sanitize_request_arg( $value, $request, $param ); 1080 1081 return $value; 1082 } 1083 1084 /** 1085 * Determines if an IP address is valid. 1086 * 1087 * Handles both IPv4 and IPv6 addresses. 1088 * 1089 * @since 4.7.0 1090 * 1091 * @param string $ip IP address. 1092 * @return string|false The valid IP address, otherwise false. 1093 */ 1094 function rest_is_ip_address( $ip ) { 1095 $ipv4_pattern = '/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/'; 1096 1097 if ( ! preg_match( $ipv4_pattern, $ip ) && ! Requests_IPv6::check_ipv6( $ip ) ) { 1098 return false; 1099 } 1100 1101 return $ip; 1102 } 1103 1104 /** 1105 * Changes a boolean-like value into the proper boolean value. 1106 * 1107 * @since 4.7.0 1108 * 1109 * @param bool|string|int $value The value being evaluated. 1110 * @return boolean Returns the proper associated boolean value. 1111 */ 1112 function rest_sanitize_boolean( $value ) { 1113 // String values are translated to `true`; make sure 'false' is false. 1114 if ( is_string( $value ) ) { 1115 $value = strtolower( $value ); 1116 if ( in_array( $value, array( 'false', '0' ), true ) ) { 1117 $value = false; 1118 } 1119 } 1120 1121 // Everything else will map nicely to boolean. 1122 return (bool) $value; 1123 } 1124 1125 /** 1126 * Determines if a given value is boolean-like. 1127 * 1128 * @since 4.7.0 1129 * 1130 * @param bool|string $maybe_bool The value being evaluated. 1131 * @return boolean True if a boolean, otherwise false. 1132 */ 1133 function rest_is_boolean( $maybe_bool ) { 1134 if ( is_bool( $maybe_bool ) ) { 1135 return true; 1136 } 1137 1138 if ( is_string( $maybe_bool ) ) { 1139 $maybe_bool = strtolower( $maybe_bool ); 1140 1141 $valid_boolean_values = array( 1142 'false', 1143 'true', 1144 '0', 1145 '1', 1146 ); 1147 1148 return in_array( $maybe_bool, $valid_boolean_values, true ); 1149 } 1150 1151 if ( is_int( $maybe_bool ) ) { 1152 return in_array( $maybe_bool, array( 0, 1 ), true ); 1153 } 1154 1155 return false; 1156 } 1157 1158 /** 1159 * Retrieves the avatar urls in various sizes. 1160 * 1161 * @since 4.7.0 1162 * 1163 * @see get_avatar_url() 1164 * 1165 * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash, 1166 * user email, WP_User object, WP_Post object, or WP_Comment object. 1167 * @return array Avatar URLs keyed by size. Each value can be a URL string or boolean false. 1168 */ 1169 function rest_get_avatar_urls( $id_or_email ) { 1170 $avatar_sizes = rest_get_avatar_sizes(); 1171 1172 $urls = array(); 1173 foreach ( $avatar_sizes as $size ) { 1174 $urls[ $size ] = get_avatar_url( $id_or_email, array( 'size' => $size ) ); 1175 } 1176 1177 return $urls; 1178 } 1179 1180 /** 1181 * Retrieves the pixel sizes for avatars. 1182 * 1183 * @since 4.7.0 1184 * 1185 * @return int[] List of pixel sizes for avatars. Default `[ 24, 48, 96 ]`. 1186 */ 1187 function rest_get_avatar_sizes() { 1188 /** 1189 * Filters the REST avatar sizes. 1190 * 1191 * Use this filter to adjust the array of sizes returned by the 1192 * `rest_get_avatar_sizes` function. 1193 * 1194 * @since 4.4.0 1195 * 1196 * @param int[] $sizes An array of int values that are the pixel sizes for avatars. 1197 * Default `[ 24, 48, 96 ]`. 1198 */ 1199 return apply_filters( 'rest_avatar_sizes', array( 24, 48, 96 ) ); 1200 } 1201 1202 /** 1203 * Validate a value based on a schema. 1204 * 1205 * @since 4.7.0 1206 * 1207 * @param mixed $value The value to validate. 1208 * @param array $args Schema array to use for validation. 1209 * @param string $param The parameter name, used in error messages. 1210 * @return true|WP_Error 1211 */ 1212 function rest_validate_value_from_schema( $value, $args, $param = '' ) { 1213 if ( is_array( $args['type'] ) ) { 1214 foreach ( $args['type'] as $type ) { 1215 $type_args = $args; 1216 $type_args['type'] = $type; 1217 1218 if ( true === rest_validate_value_from_schema( $value, $type_args, $param ) ) { 1219 return true; 1220 } 1221 } 1222 1223 /* translators: 1: Parameter, 2: List of types. */ 1224 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, implode( ',', $args['type'] ) ) ); 1225 } 1226 1227 if ( 'array' === $args['type'] ) { 1228 if ( ! is_null( $value ) ) { 1229 $value = wp_parse_list( $value ); 1230 } 1231 if ( ! wp_is_numeric_array( $value ) ) { 1232 /* translators: 1: Parameter, 2: Type name. */ 1233 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'array' ) ); 1234 } 1235 foreach ( $value as $index => $v ) { 1236 $is_valid = rest_validate_value_from_schema( $v, $args['items'], $param . '[' . $index . ']' ); 1237 if ( is_wp_error( $is_valid ) ) { 1238 return $is_valid; 1239 } 1240 } 1241 } 1242 1243 if ( 'object' === $args['type'] ) { 1244 if ( $value instanceof stdClass ) { 1245 $value = (array) $value; 1246 } 1247 1248 if ( $value instanceof JsonSerializable ) { 1249 $value = $value->jsonSerialize(); 1250 } 1251 1252 if ( ! is_array( $value ) ) { 1253 /* translators: 1: Parameter, 2: Type name. */ 1254 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'object' ) ); 1255 } 1256 1257 foreach ( $value as $property => $v ) { 1258 if ( isset( $args['properties'][ $property ] ) ) { 1259 $is_valid = rest_validate_value_from_schema( $v, $args['properties'][ $property ], $param . '[' . $property . ']' ); 1260 if ( is_wp_error( $is_valid ) ) { 1261 return $is_valid; 1262 } 1263 } elseif ( isset( $args['additionalProperties'] ) ) { 1264 if ( false === $args['additionalProperties'] ) { 1265 /* translators: %s: Property of an object. */ 1266 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not a valid property of Object.' ), $property ) ); 1267 } 1268 1269 if ( is_array( $args['additionalProperties'] ) ) { 1270 $is_valid = rest_validate_value_from_schema( $v, $args['additionalProperties'], $param . '[' . $property . ']' ); 1271 if ( is_wp_error( $is_valid ) ) { 1272 return $is_valid; 1273 } 1274 } 1275 } 1276 } 1277 } 1278 1279 if ( 'null' === $args['type'] ) { 1280 if ( null !== $value ) { 1281 /* translators: 1: Parameter, 2: Type name. */ 1282 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'null' ) ); 1283 } 1284 1285 return true; 1286 } 1287 1288 if ( ! empty( $args['enum'] ) ) { 1289 if ( ! in_array( $value, $args['enum'], true ) ) { 1290 /* translators: 1: Parameter, 2: List of valid values. */ 1291 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not one of %2$s.' ), $param, implode( ', ', $args['enum'] ) ) ); 1292 } 1293 } 1294 1295 if ( in_array( $args['type'], array( 'integer', 'number' ) ) && ! is_numeric( $value ) ) { 1296 /* translators: 1: Parameter, 2: Type name. */ 1297 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, $args['type'] ) ); 1298 } 1299 1300 if ( 'integer' === $args['type'] && round( floatval( $value ) ) !== floatval( $value ) ) { 1301 /* translators: 1: Parameter, 2: Type name. */ 1302 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'integer' ) ); 1303 } 1304 1305 if ( 'boolean' === $args['type'] && ! rest_is_boolean( $value ) ) { 1306 /* translators: 1: Parameter, 2: Type name. */ 1307 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'boolean' ) ); 1308 } 1309 1310 if ( 'string' === $args['type'] && ! is_string( $value ) ) { 1311 /* translators: 1: Parameter, 2: Type name. */ 1312 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'string' ) ); 1313 } 1314 1315 if ( isset( $args['format'] ) ) { 1316 switch ( $args['format'] ) { 1317 case 'date-time': 1318 if ( ! rest_parse_date( $value ) ) { 1319 return new WP_Error( 'rest_invalid_date', __( 'Invalid date.' ) ); 1320 } 1321 break; 1322 1323 case 'email': 1324 if ( ! is_email( $value ) ) { 1325 return new WP_Error( 'rest_invalid_email', __( 'Invalid email address.' ) ); 1326 } 1327 break; 1328 case 'ip': 1329 if ( ! rest_is_ip_address( $value ) ) { 1330 /* translators: %s: IP address. */ 1331 return new WP_Error( 'rest_invalid_param', sprintf( __( '%s is not a valid IP address.' ), $param ) ); 1332 } 1333 break; 1334 } 1335 } 1336 1337 if ( in_array( $args['type'], array( 'number', 'integer' ), true ) && ( isset( $args['minimum'] ) || isset( $args['maximum'] ) ) ) { 1338 if ( isset( $args['minimum'] ) && ! isset( $args['maximum'] ) ) { 1339 if ( ! empty( $args['exclusiveMinimum'] ) && $value <= $args['minimum'] ) { 1340 /* translators: 1: Parameter, 2: Minimum number. */ 1341 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be greater than %2$d' ), $param, $args['minimum'] ) ); 1342 } elseif ( empty( $args['exclusiveMinimum'] ) && $value < $args['minimum'] ) { 1343 /* translators: 1: Parameter, 2: Minimum number. */ 1344 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be greater than or equal to %2$d' ), $param, $args['minimum'] ) ); 1345 } 1346 } elseif ( isset( $args['maximum'] ) && ! isset( $args['minimum'] ) ) { 1347 if ( ! empty( $args['exclusiveMaximum'] ) && $value >= $args['maximum'] ) { 1348 /* translators: 1: Parameter, 2: Maximum number. */ 1349 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be less than %2$d' ), $param, $args['maximum'] ) ); 1350 } elseif ( empty( $args['exclusiveMaximum'] ) && $value > $args['maximum'] ) { 1351 /* translators: 1: Parameter, 2: Maximum number. */ 1352 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be less than or equal to %2$d' ), $param, $args['maximum'] ) ); 1353 } 1354 } elseif ( isset( $args['maximum'] ) && isset( $args['minimum'] ) ) { 1355 if ( ! empty( $args['exclusiveMinimum'] ) && ! empty( $args['exclusiveMaximum'] ) ) { 1356 if ( $value >= $args['maximum'] || $value <= $args['minimum'] ) { 1357 /* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */ 1358 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be between %2$d (exclusive) and %3$d (exclusive)' ), $param, $args['minimum'], $args['maximum'] ) ); 1359 } 1360 } elseif ( empty( $args['exclusiveMinimum'] ) && ! empty( $args['exclusiveMaximum'] ) ) { 1361 if ( $value >= $args['maximum'] || $value < $args['minimum'] ) { 1362 /* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */ 1363 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be between %2$d (inclusive) and %3$d (exclusive)' ), $param, $args['minimum'], $args['maximum'] ) ); 1364 } 1365 } elseif ( ! empty( $args['exclusiveMinimum'] ) && empty( $args['exclusiveMaximum'] ) ) { 1366 if ( $value > $args['maximum'] || $value <= $args['minimum'] ) { 1367 /* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */ 1368 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be between %2$d (exclusive) and %3$d (inclusive)' ), $param, $args['minimum'], $args['maximum'] ) ); 1369 } 1370 } elseif ( empty( $args['exclusiveMinimum'] ) && empty( $args['exclusiveMaximum'] ) ) { 1371 if ( $value > $args['maximum'] || $value < $args['minimum'] ) { 1372 /* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */ 1373 return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s must be between %2$d (inclusive) and %3$d (inclusive)' ), $param, $args['minimum'], $args['maximum'] ) ); 1374 } 1375 } 1376 } 1377 } 1378 1379 return true; 1380 } 1381 1382 /** 1383 * Sanitize a value based on a schema. 1384 * 1385 * @since 4.7.0 1386 * 1387 * @param mixed $value The value to sanitize. 1388 * @param array $args Schema array to use for sanitization. 1389 * @return true|WP_Error 1390 */ 1391 function rest_sanitize_value_from_schema( $value, $args ) { 1392 if ( is_array( $args['type'] ) ) { 1393 // Determine which type the value was validated against, and use that type when performing sanitization 1394 $validated_type = ''; 1395 1396 foreach ( $args['type'] as $type ) { 1397 $type_args = $args; 1398 $type_args['type'] = $type; 1399 1400 if ( ! is_wp_error( rest_validate_value_from_schema( $value, $type_args ) ) ) { 1401 $validated_type = $type; 1402 break; 1403 } 1404 } 1405 1406 if ( ! $validated_type ) { 1407 return null; 1408 } 1409 1410 $args['type'] = $validated_type; 1411 } 1412 1413 if ( 'array' === $args['type'] ) { 1414 if ( empty( $args['items'] ) ) { 1415 return (array) $value; 1416 } 1417 $value = wp_parse_list( $value ); 1418 foreach ( $value as $index => $v ) { 1419 $value[ $index ] = rest_sanitize_value_from_schema( $v, $args['items'] ); 1420 } 1421 // Normalize to numeric array so nothing unexpected 1422 // is in the keys. 1423 $value = array_values( $value ); 1424 return $value; 1425 } 1426 1427 if ( 'object' === $args['type'] ) { 1428 if ( $value instanceof stdClass ) { 1429 $value = (array) $value; 1430 } 1431 1432 if ( $value instanceof JsonSerializable ) { 1433 $value = $value->jsonSerialize(); 1434 } 1435 1436 if ( ! is_array( $value ) ) { 1437 return array(); 1438 } 1439 1440 foreach ( $value as $property => $v ) { 1441 if ( isset( $args['properties'][ $property ] ) ) { 1442 $value[ $property ] = rest_sanitize_value_from_schema( $v, $args['properties'][ $property ] ); 1443 } elseif ( isset( $args['additionalProperties'] ) ) { 1444 if ( false === $args['additionalProperties'] ) { 1445 unset( $value[ $property ] ); 1446 } elseif ( is_array( $args['additionalProperties'] ) ) { 1447 $value[ $property ] = rest_sanitize_value_from_schema( $v, $args['additionalProperties'] ); 1448 } 1449 } 1450 } 1451 1452 return $value; 1453 } 1454 1455 if ( 'null' === $args['type'] ) { 1456 return null; 1457 } 1458 1459 if ( 'integer' === $args['type'] ) { 1460 return (int) $value; 1461 } 1462 1463 if ( 'number' === $args['type'] ) { 1464 return (float) $value; 1465 } 1466 1467 if ( 'boolean' === $args['type'] ) { 1468 return rest_sanitize_boolean( $value ); 1469 } 1470 1471 if ( isset( $args['format'] ) ) { 1472 switch ( $args['format'] ) { 1473 case 'date-time': 1474 return sanitize_text_field( $value ); 1475 1476 case 'email': 1477 /* 1478 * sanitize_email() validates, which would be unexpected. 1479 */ 1480 return sanitize_text_field( $value ); 1481 1482 case 'uri': 1483 return esc_url_raw( $value ); 1484 1485 case 'ip': 1486 return sanitize_text_field( $value ); 1487 } 1488 } 1489 1490 if ( 'string' === $args['type'] ) { 1491 return strval( $value ); 1492 } 1493 1494 return $value; 1495 } 1496 1497 /** 1498 * Append result of internal request to REST API for purpose of preloading data to be attached to a page. 1499 * Expected to be called in the context of `array_reduce`. 1500 * 1501 * @since 5.0.0 1502 * 1503 * @param array $memo Reduce accumulator. 1504 * @param string $path REST API path to preload. 1505 * @return array Modified reduce accumulator. 1506 */ 1507 function rest_preload_api_request( $memo, $path ) { 1508 // array_reduce() doesn't support passing an array in PHP 5.2, so we need to make sure we start with one. 1509 if ( ! is_array( $memo ) ) { 1510 $memo = array(); 1511 } 1512 1513 if ( empty( $path ) ) { 1514 return $memo; 1515 } 1516 1517 $method = 'GET'; 1518 if ( is_array( $path ) && 2 === count( $path ) ) { 1519 $method = end( $path ); 1520 $path = reset( $path ); 1521 1522 if ( ! in_array( $method, array( 'GET', 'OPTIONS' ), true ) ) { 1523 $method = 'GET'; 1524 } 1525 } 1526 1527 $path_parts = parse_url( $path ); 1528 if ( false === $path_parts ) { 1529 return $memo; 1530 } 1531 1532 $request = new WP_REST_Request( $method, $path_parts['path'] ); 1533 if ( ! empty( $path_parts['query'] ) ) { 1534 parse_str( $path_parts['query'], $query_params ); 1535 $request->set_query_params( $query_params ); 1536 } 1537 1538 $response = rest_do_request( $request ); 1539 if ( 200 === $response->status ) { 1540 $server = rest_get_server(); 1541 $data = (array) $response->get_data(); 1542 $links = $server::get_compact_response_links( $response ); 1543 if ( ! empty( $links ) ) { 1544 $data['_links'] = $links; 1545 } 1546 1547 if ( 'OPTIONS' === $method ) { 1548 $response = rest_send_allow_header( $response, $server, $request ); 1549 1550 $memo[ $method ][ $path ] = array( 1551 'body' => $data, 1552 'headers' => $response->headers, 1553 ); 1554 } else { 1555 $memo[ $path ] = array( 1556 'body' => $data, 1557 'headers' => $response->headers, 1558 ); 1559 } 1560 } 1561 1562 return $memo; 1563 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Jan 21 01:00:03 2020 | Cross-referenced by PHPXref 0.7.1 |