--- a/wp/wp-includes/http.php Thu Sep 29 08:06:27 2022 +0200
+++ b/wp/wp-includes/http.php Fri Sep 05 18:40:08 2025 +0200
@@ -27,18 +27,23 @@
}
/**
- * Retrieve the raw response from a safe HTTP request.
+ * Retrieves the raw response from a safe HTTP request.
*
* This function is ideal when the HTTP request is being made to an arbitrary
- * URL. The URL is validated to avoid redirection and request forgery attacks.
+ * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
+ * to avoid Server Side Request Forgery attacks (SSRF).
*
* @since 3.6.0
*
* @see wp_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information.
+ * @see wp_http_validate_url() For more information about how the URL is validated.
+ *
+ * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_request( $url, $args = array() ) {
@@ -48,18 +53,23 @@
}
/**
- * Retrieve the raw response from a safe HTTP request using the GET method.
+ * Retrieves the raw response from a safe HTTP request using the GET method.
*
* This function is ideal when the HTTP request is being made to an arbitrary
- * URL. The URL is validated to avoid redirection and request forgery attacks.
+ * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
+ * to avoid Server Side Request Forgery attacks (SSRF).
*
* @since 3.6.0
*
* @see wp_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information.
+ * @see wp_http_validate_url() For more information about how the URL is validated.
+ *
+ * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_get( $url, $args = array() ) {
@@ -69,18 +79,23 @@
}
/**
- * Retrieve the raw response from a safe HTTP request using the POST method.
+ * Retrieves the raw response from a safe HTTP request using the POST method.
*
* This function is ideal when the HTTP request is being made to an arbitrary
- * URL. The URL is validated to avoid redirection and request forgery attacks.
+ * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
+ * to avoid Server Side Request Forgery attacks (SSRF).
*
* @since 3.6.0
*
* @see wp_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information.
+ * @see wp_http_validate_url() For more information about how the URL is validated.
+ *
+ * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_post( $url, $args = array() ) {
@@ -90,18 +105,23 @@
}
/**
- * Retrieve the raw response from a safe HTTP request using the HEAD method.
+ * Retrieves the raw response from a safe HTTP request using the HEAD method.
*
* This function is ideal when the HTTP request is being made to an arbitrary
- * URL. The URL is validated to avoid redirection and request forgery attacks.
+ * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
+ * to avoid Server Side Request Forgery attacks (SSRF).
*
* @since 3.6.0
*
* @see wp_remote_request() For more information on the response array format.
* @see WP_Http::request() For default arguments information.
+ * @see wp_http_validate_url() For more information about how the URL is validated.
+ *
+ * @link https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_head( $url, $args = array() ) {
@@ -125,6 +145,7 @@
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error {
* The response array or a WP_Error on failure.
*
@@ -155,6 +176,7 @@
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_get( $url, $args = array() ) {
@@ -172,6 +194,7 @@
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_post( $url, $args = array() ) {
@@ -189,6 +212,7 @@
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
+ * See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_head( $url, $args = array() ) {
@@ -197,15 +221,16 @@
}
/**
- * Retrieve only the headers from the raw response.
+ * Retrieves only the headers from the raw response.
*
* @since 2.7.0
- * @since 4.6.0 Return value changed from an array to an Requests_Utility_CaseInsensitiveDictionary instance.
+ * @since 4.6.0 Return value changed from an array to an WpOrg\Requests\Utility\CaseInsensitiveDictionary instance.
*
- * @see \Requests_Utility_CaseInsensitiveDictionary
+ * @see \WpOrg\Requests\Utility\CaseInsensitiveDictionary
*
* @param array|WP_Error $response HTTP response.
- * @return array|\Requests_Utility_CaseInsensitiveDictionary The headers of the response. Empty array if incorrect parameter given.
+ * @return \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array The headers of the response, or empty array
+ * if incorrect parameter given.
*/
function wp_remote_retrieve_headers( $response ) {
if ( is_wp_error( $response ) || ! isset( $response['headers'] ) ) {
@@ -216,7 +241,7 @@
}
/**
- * Retrieve a single header by name from the raw response.
+ * Retrieves a single header by name from the raw response.
*
* @since 2.7.0
*
@@ -238,14 +263,14 @@
}
/**
- * Retrieve only the response code from the raw response.
+ * Retrieves only the response code from the raw response.
*
* Will return an empty string if incorrect parameter value is given.
*
* @since 2.7.0
*
* @param array|WP_Error $response HTTP response.
- * @return int|string The response code as an integer. Empty string on incorrect parameter given.
+ * @return int|string The response code as an integer. Empty string if incorrect parameter given.
*/
function wp_remote_retrieve_response_code( $response ) {
if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) {
@@ -256,14 +281,14 @@
}
/**
- * Retrieve only the response message from the raw response.
+ * Retrieves only the response message from the raw response.
*
* Will return an empty string if incorrect parameter value is given.
*
* @since 2.7.0
*
* @param array|WP_Error $response HTTP response.
- * @return string The response message. Empty string on incorrect parameter given.
+ * @return string The response message. Empty string if incorrect parameter given.
*/
function wp_remote_retrieve_response_message( $response ) {
if ( is_wp_error( $response ) || ! isset( $response['response'] ) || ! is_array( $response['response'] ) ) {
@@ -274,7 +299,7 @@
}
/**
- * Retrieve only the body from the raw response.
+ * Retrieves only the body from the raw response.
*
* @since 2.7.0
*
@@ -290,12 +315,13 @@
}
/**
- * Retrieve only the cookies from the raw response.
+ * Retrieves only the cookies from the raw response.
*
* @since 4.4.0
*
* @param array|WP_Error $response HTTP response.
- * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response. Empty array if there are none, or the response is a WP_Error.
+ * @return WP_Http_Cookie[] An array of `WP_Http_Cookie` objects from the response.
+ * Empty array if there are none, or the response is a WP_Error.
*/
function wp_remote_retrieve_cookies( $response ) {
if ( is_wp_error( $response ) || empty( $response['cookies'] ) ) {
@@ -306,13 +332,14 @@
}
/**
- * Retrieve a single cookie by name from the raw response.
+ * Retrieves a single cookie by name from the raw response.
*
* @since 4.4.0
*
* @param array|WP_Error $response HTTP response.
* @param string $name The name of the cookie to retrieve.
- * @return WP_Http_Cookie|string The `WP_Http_Cookie` object. Empty string if the cookie isn't present in the response.
+ * @return WP_Http_Cookie|string The `WP_Http_Cookie` object, or empty string
+ * if the cookie is not present in the response.
*/
function wp_remote_retrieve_cookie( $response, $name ) {
$cookies = wp_remote_retrieve_cookies( $response );
@@ -331,18 +358,19 @@
}
/**
- * Retrieve a single cookie's value by name from the raw response.
+ * Retrieves a single cookie's value by name from the raw response.
*
* @since 4.4.0
*
* @param array|WP_Error $response HTTP response.
* @param string $name The name of the cookie to retrieve.
- * @return string The value of the cookie. Empty string if the cookie isn't present in the response.
+ * @return string The value of the cookie, or empty string
+ * if the cookie is not present in the response.
*/
function wp_remote_retrieve_cookie_value( $response, $name ) {
$cookie = wp_remote_retrieve_cookie( $response, $name );
- if ( ! is_a( $cookie, 'WP_Http_Cookie' ) ) {
+ if ( ! ( $cookie instanceof WP_Http_Cookie ) ) {
return '';
}
@@ -368,7 +396,7 @@
$count = count( $capabilities );
// If we have a numeric $capabilities array, spoof a wp_remote_request() associative $args array.
- if ( $count && count( array_filter( array_keys( $capabilities ), 'is_numeric' ) ) == $count ) {
+ if ( $count && count( array_filter( array_keys( $capabilities ), 'is_numeric' ) ) === $count ) {
$capabilities = array_combine( array_values( $capabilities ), array_fill( 0, $count, true ) );
}
@@ -383,7 +411,7 @@
}
/**
- * Get the HTTP Origin of the current request.
+ * Gets the HTTP Origin of the current request.
*
* @since 3.4.0
*
@@ -396,7 +424,7 @@
}
/**
- * Change the origin of an HTTP request.
+ * Changes the origin of an HTTP request.
*
* @since 3.4.0
*
@@ -406,7 +434,7 @@
}
/**
- * Retrieve list of allowed HTTP origins.
+ * Retrieves list of allowed HTTP origins.
*
* @since 3.4.0
*
@@ -427,7 +455,7 @@
);
/**
- * Change the origin types allowed for HTTP requests.
+ * Changes the origin types allowed for HTTP requests.
*
* @since 3.4.0
*
@@ -448,7 +476,7 @@
*
* @since 3.4.0
*
- * @param null|string $origin Origin URL. If not provided, the value of get_http_origin() is used.
+ * @param string|null $origin Origin URL. If not provided, the value of get_http_origin() is used.
* @return string Origin URL if allowed, empty string if not.
*/
function is_allowed_http_origin( $origin = null ) {
@@ -463,7 +491,7 @@
}
/**
- * Change the allowed HTTP origin result.
+ * Changes the allowed HTTP origin result.
*
* @since 3.4.0
*
@@ -474,7 +502,7 @@
}
/**
- * Send Access-Control-Allow-Origin and related headers if the current request
+ * Sends Access-Control-Allow-Origin and related headers if the current request
* is from an allowed origin.
*
* If the request is an OPTIONS request, the script exits with either access
@@ -507,7 +535,21 @@
}
/**
- * Validate a URL for safe use in the HTTP API.
+ * Validates a URL for safe use in the HTTP API.
+ *
+ * Examples of URLs that are considered unsafe:
+ *
+ * - ftp://example.com/caniload.php - Invalid protocol - only http and https are allowed.
+ * - http:///example.com/caniload.php - Malformed URL.
+ * - http://user:pass@example.com/caniload.php - Login information.
+ * - http://exampleeeee.com/caniload.php - Invalid hostname, as the IP cannot be looked up in DNS.
+ *
+ * Examples of URLs that are considered unsafe by default:
+ *
+ * - http://192.168.0.1/caniload.php - IPs from LAN networks.
+ * This can be changed with the {@see 'http_request_host_is_external'} filter.
+ * - http://198.143.164.252:81/caniload.php - By default, only 80, 443, and 8080 ports are allowed.
+ * This can be changed with the {@see 'http_allowed_safe_ports'} filter.
*
* @since 3.5.2
*
@@ -559,7 +601,7 @@
) {
// If host appears local, reject unless specifically allowed.
/**
- * Check if HTTP request is external or not.
+ * Checks if HTTP request is external or not.
*
* Allows to change and allow external requests for the HTTP request.
*
@@ -589,7 +631,7 @@
*
* @since 5.9.0
*
- * @param array $allowed_ports Array of integers for valid ports.
+ * @param int[] $allowed_ports Array of integers for valid ports.
* @param string $host Host name of the requested URL.
* @param string $url Requested URL.
*/
@@ -606,7 +648,7 @@
}
/**
- * Mark allowed redirect hosts safe for HTTP requests as well.
+ * Marks allowed redirect hosts safe for HTTP requests as well.
*
* Attached to the {@see 'http_request_host_is_external'} filter.
*
@@ -682,10 +724,10 @@
$to_unset = array();
$url = (string) $url;
- if ( '//' === substr( $url, 0, 2 ) ) {
+ if ( str_starts_with( $url, '//' ) ) {
$to_unset[] = 'scheme';
$url = 'placeholder:' . $url;
- } elseif ( '/' === substr( $url, 0, 1 ) ) {
+ } elseif ( str_starts_with( $url, '/' ) ) {
$to_unset[] = 'scheme';
$to_unset[] = 'host';
$url = 'placeholder://placeholder' . $url;
@@ -707,7 +749,7 @@
}
/**
- * Retrieve a specific component from a parsed URL array.
+ * Retrieves a specific component from a parsed URL array.
*
* @internal
*
@@ -739,7 +781,7 @@
}
/**
- * Translate a PHP_URL_* constant to the named array keys PHP uses.
+ * Translates a PHP_URL_* constant to the named array keys PHP uses.
*
* @internal
*