[ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Core HTTP Request API 4 * 5 * Standardizes the HTTP requests for WordPress. Handles cookies, gzip encoding and decoding, chunk 6 * decoding, if HTTP 1.1 and various other difficult HTTP protocol implementations. 7 * 8 * @package WordPress 9 * @subpackage HTTP 10 */ 11 12 /** 13 * Returns the initialized WP_Http Object 14 * 15 * @since 2.7.0 16 * @access private 17 * 18 * @return WP_Http HTTP Transport object. 19 */ 20 function _wp_http_get_object() { 21 static $http = null; 22 23 if ( is_null( $http ) ) { 24 $http = new WP_Http(); 25 } 26 return $http; 27 } 28 29 /** 30 * Retrieves the raw response from a safe HTTP request. 31 * 32 * This function is ideal when the HTTP request is being made to an arbitrary 33 * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url() 34 * to avoid Server Side Request Forgery attacks (SSRF). 35 * 36 * The only supported protocols are `http` and `https`. 37 * 38 * @since 3.6.0 39 * 40 * @see wp_remote_request() For more information on the response array format. 41 * @see WP_Http::request() For default arguments information. 42 * @see wp_http_validate_url() For more information about how the URL is validated. 43 * 44 * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery 45 * 46 * @param string $url URL to retrieve. 47 * @param array $args Optional. Request arguments. Default empty array. 48 * See WP_Http::request() for information on accepted arguments. 49 * @return array|WP_Error The response or WP_Error on failure. 50 * See WP_Http::request() for information on return value. 51 */ 52 function wp_safe_remote_request( $url, $args = array() ) { 53 $args['reject_unsafe_urls'] = true; 54 $http = _wp_http_get_object(); 55 return $http->request( $url, $args ); 56 } 57 58 /** 59 * Retrieves the raw response from a safe HTTP request using the GET method. 60 * 61 * This function is ideal when the HTTP request is being made to an arbitrary 62 * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url() 63 * to avoid Server Side Request Forgery attacks (SSRF). 64 * 65 * The only supported protocols are `http` and `https`. 66 * 67 * @since 3.6.0 68 * 69 * @see wp_remote_request() For more information on the response array format. 70 * @see WP_Http::request() For default arguments information. 71 * @see wp_http_validate_url() For more information about how the URL is validated. 72 * 73 * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery 74 * 75 * @param string $url URL to retrieve. 76 * @param array $args Optional. Request arguments. Default empty array. 77 * See WP_Http::request() for information on accepted arguments. 78 * @return array|WP_Error The response or WP_Error on failure. 79 * See WP_Http::request() for information on return value. 80 */ 81 function wp_safe_remote_get( $url, $args = array() ) { 82 $args['reject_unsafe_urls'] = true; 83 $http = _wp_http_get_object(); 84 return $http->get( $url, $args ); 85 } 86 87 /** 88 * Retrieves the raw response from a safe HTTP request using the POST method. 89 * 90 * This function is ideal when the HTTP request is being made to an arbitrary 91 * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url() 92 * to avoid Server Side Request Forgery attacks (SSRF). 93 * 94 * The only supported protocols are `http` and `https`. 95 * 96 * @since 3.6.0 97 * 98 * @see wp_remote_request() For more information on the response array format. 99 * @see WP_Http::request() For default arguments information. 100 * @see wp_http_validate_url() For more information about how the URL is validated. 101 * 102 * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery 103 * 104 * @param string $url URL to retrieve. 105 * @param array $args Optional. Request arguments. Default empty array. 106 * See WP_Http::request() for information on accepted arguments. 107 * @return array|WP_Error The response or WP_Error on failure. 108 * See WP_Http::request() for information on return value. 109 */ 110 function wp_safe_remote_post( $url, $args = array() ) { 111 $args['reject_unsafe_urls'] = true; 112 $http = _wp_http_get_object(); 113 return $http->post( $url, $args ); 114 } 115 116 /** 117 * Retrieves the raw response from a safe HTTP request using the HEAD method. 118 * 119 * This function is ideal when the HTTP request is being made to an arbitrary 120 * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url() 121 * to avoid Server Side Request Forgery attacks (SSRF). 122 * 123 * The only supported protocols are `http` and `https`. 124 * 125 * @since 3.6.0 126 * 127 * @see wp_remote_request() For more information on the response array format. 128 * @see WP_Http::request() For default arguments information. 129 * @see wp_http_validate_url() For more information about how the URL is validated. 130 * 131 * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery 132 * 133 * @param string $url URL to retrieve. 134 * @param array $args Optional. Request arguments. Default empty array. 135 * See WP_Http::request() for information on accepted arguments. 136 * @return array|WP_Error The response or WP_Error on failure. 137 * See WP_Http::request() for information on return value. 138 */ 139 function wp_safe_remote_head( $url, $args = array() ) { 140 $args['reject_unsafe_urls'] = true; 141 $http = _wp_http_get_object(); 142 return $http->head( $url, $args ); 143 } 144 145 /** 146 * Performs an HTTP request and returns its response. 147 * 148 * There are other API functions available which abstract away the HTTP method: 149 * 150 * - Default 'GET' for wp_remote_get() 151 * - Default 'POST' for wp_remote_post() 152 * - Default 'HEAD' for wp_remote_head() 153 * 154 * Important: If the URL is user-controlled, use `wp_safe_remote_request()` instead. 155 * 156 * @since 2.7.0 157 * 158 * @see WP_Http::request() For information on default arguments. 159 * 160 * @param string $url URL to retrieve. 161 * @param array $args Optional. Request arguments. Default empty array. 162 * See WP_Http::request() for information on accepted arguments. 163 * @return array|WP_Error The response array or a WP_Error on failure. 164 * See WP_Http::request() for information on return value. 165 */ 166 function wp_remote_request( $url, $args = array() ) { 167 $http = _wp_http_get_object(); 168 return $http->request( $url, $args ); 169 } 170 171 /** 172 * Performs an HTTP request using the GET method and returns its response. 173 * 174 * Important: If the URL is user-controlled, use `wp_safe_remote_get()` instead. 175 * 176 * @since 2.7.0 177 * 178 * @see wp_remote_request() For more information on the response array format. 179 * @see WP_Http::request() For default arguments information. 180 * 181 * @param string $url URL to retrieve. 182 * @param array $args Optional. Request arguments. Default empty array. 183 * See WP_Http::request() for information on accepted arguments. 184 * @return array|WP_Error The response or WP_Error on failure. 185 * See WP_Http::request() for information on return value. 186 */ 187 function wp_remote_get( $url, $args = array() ) { 188 $http = _wp_http_get_object(); 189 return $http->get( $url, $args ); 190 } 191 192 /** 193 * Performs an HTTP request using the POST method and returns its response. 194 * 195 * Important: If the URL is user-controlled, use `wp_safe_remote_post()` instead. 196 * 197 * @since 2.7.0 198 * 199 * @see wp_remote_request() For more information on the response array format. 200 * @see WP_Http::request() For default arguments information. 201 * 202 * @param string $url URL to retrieve. 203 * @param array $args Optional. Request arguments. Default empty array. 204 * See WP_Http::request() for information on accepted arguments. 205 * @return array|WP_Error The response or WP_Error on failure. 206 * See WP_Http::request() for information on return value. 207 */ 208 function wp_remote_post( $url, $args = array() ) { 209 $http = _wp_http_get_object(); 210 return $http->post( $url, $args ); 211 } 212 213 /** 214 * Performs an HTTP request using the HEAD method and returns its response. 215 * 216 * Important: If the URL is user-controlled, use `wp_safe_remote_head()` instead. 217 * 218 * @since 2.7.0 219 * 220 * @see wp_remote_request() For more information on the response array format. 221 * @see WP_Http::request() For default arguments information. 222 * 223 * @param string $url URL to retrieve. 224 * @param array $args Optional. Request arguments. Default empty array. 225 * See WP_Http::request() for information on accepted arguments. 226 * @return array|WP_Error The response or WP_Error on failure. 227 * See WP_Http::request() for information on return value. 228 */ 229 function wp_remote_head( $url, $args = array() ) { 230 $http = _wp_http_get_object(); 231 return $http->head( $url, $args ); 232 } 233 234 /** 235 * Retrieves only the headers from the raw response. 236 * 237 * @since 2.7.0 238 * @since 4.6.0 Return value changed from an array to an WpOrg\Requests\Utility\CaseInsensitiveDictionary instance. 239 * 240 * @see \WpOrg\Requests\Utility\CaseInsensitiveDictionary 241 * 242 * @param array|WP_Error $response HTTP response. 243 * @return \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array The headers of the response, or empty array 244 * if incorrect parameter given. 245 */ 246 function wp_remote_retrieve_headers( $response ) { 247 if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) { 248 return array(); 249 } 250 251 return $response['headers']; 252 } 253 254 /** 255 * Retrieves a single header by name from the raw response. 256 * 257 * @since 2.7.0 258 * 259 * @param array|WP_Error $response HTTP response. 260 * @param string $header Header name to retrieve value from. 261 * @return array|string The header(s) value(s). Array if multiple headers with the same name are retrieved. 262 * Empty string if incorrect parameter given, or if the header doesn't exist. 263 */ 264 function wp_remote_retrieve_header( $response, $header ) { 265 if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) { 266 return ''; 267 } 268 269 if ( isset( $response['headers'][ $header ] ) ) { 270 return $response['headers'][ $header ]; 271 } 272 273 return ''; 274 } 275 276 /** 277 * Retrieves only the response code from the raw response. 278 * 279 * Will return an empty string if incorrect parameter value is given. 280 * 281 * @since 2.7.0 282 * 283 * @param array|WP_Error $response HTTP response. 284 * @return int|string The response code as an integer. Empty string if incorrect parameter given. 285 */ 286 function wp_remote_retrieve_response_code( $response ) { 287 if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) { 288 return ''; 289 } 290 291 return $response['response']['code']; 292 } 293 294 /** 295 * Retrieves only the response message from the raw response. 296 * 297 * Will return an empty string if incorrect parameter value is given. 298 * 299 * @since 2.7.0 300 * 301 * @param array|WP_Error $response HTTP response. 302 * @return string The response message. Empty string if incorrect parameter given. 303 */ 304 function wp_remote_retrieve_response_message( $response ) { 305 if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) { 306 return ''; 307 } 308 309 return $response['response']['message']; 310 } 311 312 /** 313 * Retrieves only the body from the raw response. 314 * 315 * @since 2.7.0 316 * 317 * @param array|WP_Error $response HTTP response. 318 * @return string The body of the response. Empty string if no body or incorrect parameter given. 319 */ 320 function wp_remote_retrieve_body( $response ) { 321 if ( is_wp_error( $response ) || ! isset( $response['body'] ) ) { 322 return ''; 323 } 324 325 return $response['body']; 326 } 327 328 /** 329 * Retrieves only the cookies from the raw response. 330 * 331 * @since 4.4.0 332 * 333 * @param array|WP_Error $response HTTP response. 334 * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response. 335 * Empty array if there are none, or the response is a WP_Error. 336 */ 337 function wp_remote_retrieve_cookies( $response ) { 338 if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) { 339 return array(); 340 } 341 342 return $response['cookies']; 343 } 344 345 /** 346 * Retrieves a single cookie by name from the raw response. 347 * 348 * @since 4.4.0 349 * 350 * @param array|WP_Error $response HTTP response. 351 * @param string $name The name of the cookie to retrieve. 352 * @return WP_Http_Cookie|string The `WP_Http_Cookie` object, or empty string 353 * if the cookie is not present in the response. 354 */ 355 function wp_remote_retrieve_cookie( $response, $name ) { 356 $cookies = wp_remote_retrieve_cookies( $response ); 357 358 if ( empty( $cookies ) ) { 359 return ''; 360 } 361 362 foreach ( $cookies as $cookie ) { 363 if ( $cookie->name === $name ) { 364 return $cookie; 365 } 366 } 367 368 return ''; 369 } 370 371 /** 372 * Retrieves a single cookie's value by name from the raw response. 373 * 374 * @since 4.4.0 375 * 376 * @param array|WP_Error $response HTTP response. 377 * @param string $name The name of the cookie to retrieve. 378 * @return string The value of the cookie, or empty string 379 * if the cookie is not present in the response. 380 */ 381 function wp_remote_retrieve_cookie_value( $response, $name ) { 382 $cookie = wp_remote_retrieve_cookie( $response, $name ); 383 384 if ( ! ( $cookie instanceof WP_Http_Cookie ) ) { 385 return ''; 386 } 387 388 return $cookie->value; 389 } 390 391 /** 392 * Determines if there is an HTTP Transport that can process this request. 393 * 394 * @since 3.2.0 395 * 396 * @param array $capabilities Array of capabilities to test or a wp_remote_request() $args array. 397 * @param string $url Optional. If given, will check if the URL requires SSL and adds 398 * that requirement to the capabilities array. 399 * 400 * @return bool 401 */ 402 function wp_http_supports( $capabilities = array(), $url = null ) { 403 $capabilities = wp_parse_args( $capabilities ); 404 405 $count = count( $capabilities ); 406 407 // If we have a numeric $capabilities array, spoof a wp_remote_request() associative $args array. 408 if ( $count && count( array_filter( array_keys( $capabilities ), 'is_numeric' ) ) === $count ) { 409 $capabilities = array_combine( array_values( $capabilities ), array_fill( 0, $count, true ) ); 410 } 411 412 if ( $url && ! isset( $capabilities['ssl'] ) ) { 413 $scheme = parse_url( $url, PHP_URL_SCHEME ); 414 if ( 'https' === $scheme || 'ssl' === $scheme ) { 415 $capabilities['ssl'] = true; 416 } 417 } 418 419 return WpOrg\Requests\Requests::has_capabilities( $capabilities ); 420 } 421 422 /** 423 * Gets the HTTP Origin of the current request. 424 * 425 * @since 3.4.0 426 * 427 * @return string URL of the origin. Empty string if no origin. 428 */ 429 function get_http_origin() { 430 $origin = ''; 431 if ( ! empty( $_SERVER['HTTP_ORIGIN'] ) ) { 432 $origin = $_SERVER['HTTP_ORIGIN']; 433 } 434 435 /** 436 * Changes the origin of an HTTP request. 437 * 438 * @since 3.4.0 439 * 440 * @param string $origin The HTTP origin for the request. 441 */ 442 return apply_filters( 'http_origin', $origin ); 443 } 444 445 /** 446 * Retrieves list of allowed HTTP origins. 447 * 448 * @since 3.4.0 449 * 450 * @return string[] Array of origin URLs. 451 */ 452 function get_allowed_http_origins() { 453 $admin_origin = parse_url( admin_url() ); 454 $home_origin = parse_url( home_url() ); 455 456 // @todo Preserve port? 457 $allowed_origins = array_unique( 458 array( 459 'http://' . $admin_origin['host'], 460 'https://' . $admin_origin['host'], 461 'http://' . $home_origin['host'], 462 'https://' . $home_origin['host'], 463 ) 464 ); 465 466 /** 467 * Changes the origin types allowed for HTTP requests. 468 * 469 * @since 3.4.0 470 * 471 * @param string[] $allowed_origins Array of allowed HTTP origins. 472 */ 473 return apply_filters( 'allowed_http_origins', $allowed_origins ); 474 } 475 476 /** 477 * Determines if the HTTP origin is an authorized one. 478 * 479 * @since 3.4.0 480 * 481 * @param string|null $origin Origin URL. If not provided, the value of get_http_origin() is used. 482 * @return string Origin URL if allowed, empty string if not. 483 */ 484 function is_allowed_http_origin( $origin = null ) { 485 $origin_arg = $origin; 486 487 if ( null === $origin ) { 488 $origin = get_http_origin(); 489 } 490 491 if ( $origin && ! in_array( $origin, get_allowed_http_origins(), true ) ) { 492 $origin = ''; 493 } 494 495 /** 496 * Changes the allowed HTTP origin result. 497 * 498 * @since 3.4.0 499 * 500 * @param string $origin Origin URL if allowed, empty string if not. 501 * @param string $origin_arg Original origin string passed into is_allowed_http_origin function. 502 */ 503 return apply_filters( 'allowed_http_origin', $origin, $origin_arg ); 504 } 505 506 /** 507 * Sends Access-Control-Allow-Origin and related headers if the current request 508 * is from an allowed origin. 509 * 510 * If the request is an OPTIONS request, the script exits with either access 511 * control headers sent, or a 403 response if the origin is not allowed. For 512 * other request methods, you will receive a return value. 513 * 514 * @since 3.4.0 515 * 516 * @return string|false Returns the origin URL if headers are sent. Returns false 517 * if headers are not sent. 518 */ 519 function send_origin_headers() { 520 $origin = get_http_origin(); 521 522 if ( is_allowed_http_origin( $origin ) ) { 523 header( 'Access-Control-Allow-Origin: ' . $origin ); 524 header( 'Access-Control-Allow-Credentials: true' ); 525 if ( 'OPTIONS' === $_SERVER['REQUEST_METHOD'] ) { 526 exit; 527 } 528 return $origin; 529 } 530 531 if ( 'OPTIONS' === $_SERVER['REQUEST_METHOD'] ) { 532 status_header( 403 ); 533 exit; 534 } 535 536 return false; 537 } 538 539 /** 540 * Validates a URL as safe for use in the HTTP API. 541 * 542 * The only supported protocols are `http` and `https`. 543 * 544 * Examples of URLs that are considered unsafe: 545 * 546 * - `ftp://example.com/caniload.php` - Invalid protocol - only http and https are allowed. 547 * - `http:///example.com/caniload.php` - Malformed URL. 548 * - `http://user:pass@example.com/caniload.php` - Login information. 549 * - `http://example.invalid/caniload.php` - Invalid hostname, as the IP cannot be looked up in DNS. 550 * 551 * Examples of URLs that are considered unsafe by default but can be allowed with filters: 552 * 553 * - `http://192.168.0.1/caniload.php` - IP address from LAN network. 554 * This can be changed with the {@see 'http_request_host_is_external'} filter. 555 * - `http://198.143.164.252:81/caniload.php` - By default, only ports 80, 443, and 8080 are allowed. 556 * This can be changed with the {@see 'http_allowed_safe_ports'} filter. 557 * 558 * @since 3.5.2 559 * 560 * @param string $url Request URL. 561 * @return string|false Returns false if the URL is not safe, or the original URL if it is safe. 562 */ 563 function wp_http_validate_url( $url ) { 564 if ( ! is_string( $url ) || '' === $url || is_numeric( $url ) ) { 565 return false; 566 } 567 568 $original_url = $url; 569 $url = wp_kses_bad_protocol( $url, array( 'http', 'https' ) ); 570 if ( ! $url || strtolower( $url ) !== strtolower( $original_url ) ) { 571 return false; 572 } 573 574 $parsed_url = parse_url( $url ); 575 if ( ! $parsed_url || empty( $parsed_url['host'] ) ) { 576 return false; 577 } 578 579 if ( isset( $parsed_url['user'] ) || isset( $parsed_url['pass'] ) ) { 580 return false; 581 } 582 583 if ( false !== strpbrk( $parsed_url['host'], ':#?[]' ) ) { 584 return false; 585 } 586 587 $parsed_home = parse_url( get_option( 'home' ) ); 588 $same_host = isset( $parsed_home['host'] ) && strtolower( $parsed_home['host'] ) === strtolower( $parsed_url['host'] ); 589 $host = trim( $parsed_url['host'], '.' ); 590 591 if ( ! $same_host ) { 592 if ( preg_match( '#^(([1-9]?\d|1\d\d|25[0-5]|2[0-4]\d)\.){3}([1-9]?\d|1\d\d|25[0-5]|2[0-4]\d)$#', $host ) ) { 593 $ip = $host; 594 } else { 595 $ip = gethostbyname( $host ); 596 if ( $ip === $host ) { // Error condition for gethostbyname(). 597 return false; 598 } 599 } 600 if ( $ip ) { 601 $parts = array_map( 'intval', explode( '.', $ip ) ); 602 if ( 127 === $parts[0] || 10 === $parts[0] || 0 === $parts[0] 603 || ( 172 === $parts[0] && 16 <= $parts[1] && 31 >= $parts[1] ) 604 || ( 192 === $parts[0] && 168 === $parts[1] ) 605 ) { 606 // If host appears local, reject unless specifically allowed. 607 /** 608 * Checks if HTTP request is external or not. 609 * 610 * Allows to change and allow external requests for the HTTP request. 611 * 612 * @since 3.6.0 613 * 614 * @param bool $external Whether HTTP request is external or not. 615 * @param string $host Host name of the requested URL. 616 * @param string $url Requested URL. 617 */ 618 if ( ! apply_filters( 'http_request_host_is_external', false, $host, $url ) ) { 619 return false; 620 } 621 } 622 } 623 } 624 625 if ( empty( $parsed_url['port'] ) ) { 626 return $url; 627 } 628 629 $port = $parsed_url['port']; 630 631 /** 632 * Controls the list of ports considered safe in HTTP API. 633 * 634 * Allows to change and allow external requests for the HTTP request. 635 * 636 * @since 5.9.0 637 * 638 * @param int[] $allowed_ports Array of integers for valid ports. Default allowed ports 639 * are 80, 443, and 8080. 640 * @param string $host Host name of the requested URL. 641 * @param string $url Requested URL. 642 */ 643 $allowed_ports = apply_filters( 'http_allowed_safe_ports', array( 80, 443, 8080 ), $host, $url ); 644 if ( is_array( $allowed_ports ) && in_array( $port, $allowed_ports, true ) ) { 645 return $url; 646 } 647 648 if ( $parsed_home && $same_host && isset( $parsed_home['port'] ) && $parsed_home['port'] === $port ) { 649 return $url; 650 } 651 652 return false; 653 } 654 655 /** 656 * Marks allowed redirect hosts safe for HTTP requests as well. 657 * 658 * Attached to the {@see 'http_request_host_is_external'} filter. 659 * 660 * @since 3.6.0 661 * 662 * @param bool $is_external 663 * @param string $host 664 * @return bool 665 */ 666 function allowed_http_request_hosts( $is_external, $host ) { 667 if ( ! $is_external && wp_validate_redirect( 'http://' . $host ) ) { 668 $is_external = true; 669 } 670 return $is_external; 671 } 672 673 /** 674 * Adds any domain in a multisite installation for safe HTTP requests to the 675 * allowed list. 676 * 677 * Attached to the {@see 'http_request_host_is_external'} filter. 678 * 679 * @since 3.6.0 680 * 681 * @global wpdb $wpdb WordPress database abstraction object. 682 * 683 * @param bool $is_external 684 * @param string $host 685 * @return bool 686 */ 687 function ms_allowed_http_request_hosts( $is_external, $host ) { 688 global $wpdb; 689 static $queried = array(); 690 if ( $is_external ) { 691 return $is_external; 692 } 693 if ( get_network()->domain === $host ) { 694 return true; 695 } 696 if ( isset( $queried[ $host ] ) ) { 697 return $queried[ $host ]; 698 } 699 $queried[ $host ] = (bool) $wpdb->get_var( $wpdb->prepare( "SELECT domain FROM $wpdb->blogs WHERE domain = %s LIMIT 1", $host ) ); 700 return $queried[ $host ]; 701 } 702 703 /** 704 * A wrapper for PHP's parse_url() function that handles consistency in the return values 705 * across PHP versions. 706 * 707 * Across various PHP versions, schemeless URLs containing a ":" in the query 708 * are being handled inconsistently. This function works around those differences. 709 * 710 * @since 4.4.0 711 * @since 4.7.0 The `$component` parameter was added for parity with PHP's `parse_url()`. 712 * 713 * @link https://www.php.net/manual/en/function.parse-url.php 714 * 715 * @param string $url The URL to parse. 716 * @param int $component The specific component to retrieve. Use one of the PHP 717 * predefined constants to specify which one. 718 * Defaults to -1 (= return all parts as an array). 719 * @return mixed False on parse failure; Array of URL components on success; 720 * When a specific component has been requested: null if the component 721 * doesn't exist in the given URL; a string or - in the case of 722 * PHP_URL_PORT - integer when it does. See parse_url()'s return values. 723 */ 724 function wp_parse_url( $url, $component = -1 ) { 725 $to_unset = array(); 726 $url = (string) $url; 727 728 if ( str_starts_with( $url, '//' ) ) { 729 $to_unset[] = 'scheme'; 730 $url = 'placeholder:' . $url; 731 } elseif ( str_starts_with( $url, '/' ) ) { 732 $to_unset[] = 'scheme'; 733 $to_unset[] = 'host'; 734 $url = 'placeholder://placeholder' . $url; 735 } 736 737 $parts = parse_url( $url ); 738 739 if ( false === $parts ) { 740 // Parsing failure. 741 return $parts; 742 } 743 744 // Remove the placeholder values. 745 foreach ( $to_unset as $key ) { 746 unset( $parts[ $key ] ); 747 } 748 749 return _get_component_from_parsed_url_array( $parts, $component ); 750 } 751 752 /** 753 * Retrieves a specific component from a parsed URL array. 754 * 755 * @internal 756 * 757 * @since 4.7.0 758 * @access private 759 * 760 * @link https://www.php.net/manual/en/function.parse-url.php 761 * 762 * @param array|false $url_parts The parsed URL. Can be false if the URL failed to parse. 763 * @param int $component The specific component to retrieve. Use one of the PHP 764 * predefined constants to specify which one. 765 * Defaults to -1 (= return all parts as an array). 766 * @return mixed False on parse failure; Array of URL components on success; 767 * When a specific component has been requested: null if the component 768 * doesn't exist in the given URL; a string or - in the case of 769 * PHP_URL_PORT - integer when it does. See parse_url()'s return values. 770 */ 771 function _get_component_from_parsed_url_array( $url_parts, $component = -1 ) { 772 if ( -1 === $component ) { 773 return $url_parts; 774 } 775 776 $key = _wp_translate_php_url_constant_to_key( $component ); 777 if ( false !== $key && is_array( $url_parts ) && isset( $url_parts[ $key ] ) ) { 778 return $url_parts[ $key ]; 779 } else { 780 return null; 781 } 782 } 783 784 /** 785 * Translates a PHP_URL_* constant to the named array keys PHP uses. 786 * 787 * @internal 788 * 789 * @since 4.7.0 790 * @access private 791 * 792 * @link https://www.php.net/manual/en/url.constants.php 793 * 794 * @param int $constant PHP_URL_* constant. 795 * @return string|false The named key or false. 796 */ 797 function _wp_translate_php_url_constant_to_key( $constant ) { 798 $translation = array( 799 PHP_URL_SCHEME => 'scheme', 800 PHP_URL_HOST => 'host', 801 PHP_URL_PORT => 'port', 802 PHP_URL_USER => 'user', 803 PHP_URL_PASS => 'pass', 804 PHP_URL_PATH => 'path', 805 PHP_URL_QUERY => 'query', 806 PHP_URL_FRAGMENT => 'fragment', 807 ); 808 809 if ( isset( $translation[ $constant ] ) ) { 810 return $translation[ $constant ]; 811 } else { 812 return false; 813 } 814 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated : Tue Sep 9 08:20:04 2025 | Cross-referenced by PHPXref |