WordPress.org
Get WordPress

Make WordPress Core

Changeset 60652

Timestamp:
08/20/2025 12:53:32 PM (7 weeks ago)
Author:
johnbillion
Message:

HTTP API: Various improvements to the docblocks for HTTP functions.

See #63166

Location:
trunk/src/wp-includes
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-http.php

    r60191 r60652  
    265265         *  - An array containing 'headers', 'body', 'response', 'cookies', and 'filename' elements
    266266         *  - A WP_Error instance
    267          *  - boolean false to avoid short-circuiting the response
     267         *  - Boolean false to avoid short-circuiting the response
    268268         *
    269269         * Returning any other value may result in unexpected behavior.

  • trunk/src/wp-includes/http.php

    r59293 r60652  
    3333 * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
    3434 * to avoid Server Side Request Forgery attacks (SSRF).
     35 *
     36 * The only supported protocols are `http` and `https`.
    3537 *
    3638 * @since 3.6.0
    … …  
    6163 * to avoid Server Side Request Forgery attacks (SSRF).
    6264 *
     65 * The only supported protocols are `http` and `https`.
     66 *
    6367 * @since 3.6.0
    6468 *
    … …  
    8892 * to avoid Server Side Request Forgery attacks (SSRF).
    8993 *
     94 * The only supported protocols are `http` and `https`.
     95 *
    9096 * @since 3.6.0
    9197 *
    … …  
    115121 * to avoid Server Side Request Forgery attacks (SSRF).
    116122 *
     123 * The only supported protocols are `http` and `https`.
     124 *
    117125 * @since 3.6.0
    118126 *
    … …  
    144152 *  - Default 'HEAD' for wp_remote_head()
    145153 *
     154 * Important: If the URL is user-controlled, use `wp_safe_remote_request()` instead.
     155 *
    146156 * @since 2.7.0
    147157 *
    … …  
    162172 * Performs an HTTP request using the GET method and returns its response.
    163173 *
     174 * Important: If the URL is user-controlled, use `wp_safe_remote_get()` instead.
     175 *
    164176 * @since 2.7.0
    165177 *
    … …  
    181193 * Performs an HTTP request using the POST method and returns its response.
    182194 *
     195 * Important: If the URL is user-controlled, use `wp_safe_remote_post()` instead.
     196 *
    183197 * @since 2.7.0
    184198 *
    … …  
    200214 * Performs an HTTP request using the HEAD method and returns its response.
    201215 *
     216 * Important: If the URL is user-controlled, use `wp_safe_remote_head()` instead.
     217 *
    202218 * @since 2.7.0
    203219 *
    … …  
    422438     * @since 3.4.0
    423439     *
    424      * @param string $origin The original origin for the request.
     440     * @param string $origin The HTTP origin for the request.
    425441     */
    426442    return apply_filters( 'http_origin', $origin );
    … …  
    453469     * @since 3.4.0
    454470     *
    455      * @param string[] $allowed_origins {
    456      *     Array of default allowed HTTP origins.
    457      *
    458      *     @type string $0 Non-secure URL for admin origin.
    459      *     @type string $1 Secure URL for admin origin.
    460      *     @type string $2 Non-secure URL for home origin.
    461      *     @type string $3 Secure URL for home origin.
    462      * }
     471     * @param string[] $allowed_origins Array of allowed HTTP origins.
    463472     */
    464473    return apply_filters( 'allowed_http_origins', $allowed_origins );
    … …  
    529538
    530539/**
    531  * Validates a URL for safe use in the HTTP API.
     540 * Validates a URL as safe for use in the HTTP API.
     541 *
     542 * The only supported protocols are `http` and `https`.
    532543 *
    533544 * Examples of URLs that are considered unsafe:
    534545 *
    535  * - ftp://example.com/caniload.php - Invalid protocol - only http and https are allowed.
    536  * - http:///example.com/caniload.php - Malformed URL.
    537  * - http://user:pass@example.com/caniload.php - Login information.
    538  * - http://example.invalid/caniload.php - Invalid hostname, as the IP cannot be looked up in DNS.
    539  *
    540  * Examples of URLs that are considered unsafe by default:
    541  *
    542  * - http://192.168.0.1/caniload.php - IPs from LAN networks.
     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.
    543554 *   This can be changed with the {@see 'http_request_host_is_external'} filter.
    544  * - http://198.143.164.252:81/caniload.php - By default, only 80, 443, and 8080 ports are allowed.
     555 * - `http://198.143.164.252:81/caniload.php` - By default, only ports 80, 443, and 8080 are allowed.
    545556 *   This can be changed with the {@see 'http_allowed_safe_ports'} filter.
    546557 *
    … …  
    548559 *
    549560 * @param string $url Request URL.
    550  * @return string|false URL or false on failure.
     561 * @return string|false Returns false if the URL is not safe, or the original URL if it is safe.
    551562 */
    552563function wp_http_validate_url( $url ) {
    … …  
    625636     * @since 5.9.0
    626637     *
    627      * @param int[]  $allowed_ports Array of integers for valid ports.
     638     * @param int[]  $allowed_ports Array of integers for valid ports. Default allowed ports
     639     *                              are 80, 443, and 8080.
    628640     * @param string $host          Host name of the requested URL.
    629641     * @param string $url           Requested URL.
Note: See TracChangeset for help on using the changeset viewer.