enmi-conf.org: comparison wp/wp-includes/http.php

equal deleted inserted replaced

-:7b1b88e27a20
+:48c4eec2b7e6
 	}
 	return $http;
 }
 /**
-* 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() ) {
 	$args['reject_unsafe_urls'] = true;
 	$http                       = _wp_http_get_object();
 	return $http->request( $url, $args );
 }
 /**
-* 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() ) {
 	$args['reject_unsafe_urls'] = true;
 	$http                       = _wp_http_get_object();
 	return $http->get( $url, $args );
 }
 /**
-* 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() ) {
 	$args['reject_unsafe_urls'] = true;
 	$http                       = _wp_http_get_object();
 	return $http->post( $url, $args );
 }
 /**
-* 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() ) {
 	$args['reject_unsafe_urls'] = true;
 	$http                       = _wp_http_get_object();
 *
 * @see WP_Http::request() For information on default arguments.
 *
 * @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.
 *
 *     @type string[]                       $headers       Array of response headers keyed by their name.
 *     @type string                         $body          Response body.
 * @see wp_remote_request() For more information on the response array format.
 * @see WP_Http::request() For default arguments information.
 *
 * @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() ) {
 	$http = _wp_http_get_object();
 	return $http->get( $url, $args );
 * @see wp_remote_request() For more information on the response array format.
 * @see WP_Http::request() For default arguments information.
 *
 * @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() ) {
 	$http = _wp_http_get_object();
 	return $http->post( $url, $args );
 * @see wp_remote_request() For more information on the response array format.
 * @see WP_Http::request() For default arguments information.
 *
 * @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() ) {
 	$http = _wp_http_get_object();
 	return $http->head( $url, $args );
 }
 /**
-* 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'] ) ) {
 		return array();
 	}
 	return $response['headers'];
 }
 /**
-* Retrieve a single header by name from the raw response.
+* Retrieves a single header by name from the raw response.
 *
 * @since 2.7.0
 *
 * @param array|WP_Error $response HTTP response.
 * @param string         $header   Header name to retrieve value from.
 	return '';
 }
 /**
-* 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'] ) ) {
 		return '';
 	}
 	return $response['response']['code'];
 }
 /**
-* 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'] ) ) {
 		return '';
 	}
 	return $response['response']['message'];
 }
 /**
-* Retrieve only the body from the raw response.
+* Retrieves only the body from the raw response.
 *
 * @since 2.7.0
 *
 * @param array|WP_Error $response HTTP response.
 * @return string The body of the response. Empty string if no body or incorrect parameter given.
 	return $response['body'];
 }
 /**
-* 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'] ) ) {
 		return array();
 	}
 	return $response['cookies'];
 }
 /**
-* 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 );
 	if ( empty( $cookies ) ) {
 	return '';
 }
 /**
-* 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 '';
 	}
 	return $cookie->value;
 }
 	$capabilities = wp_parse_args( $capabilities );
 	$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 ) );
 	}
 	if ( $url && ! isset( $capabilities['ssl'] ) ) {
 		$scheme = parse_url( $url, PHP_URL_SCHEME );
 	return (bool) $http->_get_first_available_transport( $capabilities );
 }
 /**
-* Get the HTTP Origin of the current request.
+* Gets the HTTP Origin of the current request.
 *
 * @since 3.4.0
 *
 * @return string URL of the origin. Empty string if no origin.
 */
 	if ( ! empty( $_SERVER['HTTP_ORIGIN'] ) ) {
 		$origin = $_SERVER['HTTP_ORIGIN'];
 	}
 	/**
-	 * Change the origin of an HTTP request.
+	 * Changes the origin of an HTTP request.
 	 *
 	 * @since 3.4.0
 	 *
 	 * @param string $origin The original origin for the request.
 	 */
 	return apply_filters( 'http_origin', $origin );
 }
 /**
-* Retrieve list of allowed HTTP origins.
+* Retrieves list of allowed HTTP origins.
 *
 * @since 3.4.0
 *
 * @return string[] Array of origin URLs.
 */
 			'https://' . $home_origin['host'],
 		)
 	);
 	/**
-	 * Change the origin types allowed for HTTP requests.
+	 * Changes the origin types allowed for HTTP requests.
 	 *
 	 * @since 3.4.0
 	 *
 	 * @param string[] $allowed_origins {
 	 *     Array of default allowed HTTP origins.
 /**
 * Determines if the HTTP origin is an authorized one.
 *
 * @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 ) {
 	$origin_arg = $origin;
 	if ( $origin && ! in_array( $origin, get_allowed_http_origins(), true ) ) {
 		$origin = '';
 	}
 	/**
-	 * Change the allowed HTTP origin result.
+	 * Changes the allowed HTTP origin result.
 	 *
 	 * @since 3.4.0
 	 *
 	 * @param string $origin     Origin URL if allowed, empty string if not.
 	 * @param string $origin_arg Original origin string passed into is_allowed_http_origin function.
 	 */
 	return apply_filters( 'allowed_http_origin', $origin, $origin_arg );
 }
 /**
-* 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
 * control headers sent, or a 403 response if the origin is not allowed. For
 * other request methods, you will receive a return value.
 	return false;
 }
 /**
-* 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
 *
 * @param string $url Request URL.
 * @return string|false URL or false on failure.
 				|| ( 172 === $parts[0] && 16 <= $parts[1] && 31 >= $parts[1] )
 				|| ( 192 === $parts[0] && 168 === $parts[1] )
 			) {
 				// 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.
 				 *
 				 * @since 3.6.0
 				 *
 	 *
 	 * Allows to change and allow external requests for the HTTP request.
 	 *
 	 * @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.
 	 */
 	$allowed_ports = apply_filters( 'http_allowed_safe_ports', array( 80, 443, 8080 ), $host, $url );
 	if ( is_array( $allowed_ports ) && in_array( $port, $allowed_ports, true ) ) {
 	return false;
 }
 /**
-* 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.
 *
 * @since 3.6.0
 *
 */
 function wp_parse_url( $url, $component = -1 ) {
 	$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;
 	}
 	return _get_component_from_parsed_url_array( $parts, $component );
 }
 /**
-* Retrieve a specific component from a parsed URL array.
+* Retrieves a specific component from a parsed URL array.
 *
 * @internal
 *
 * @since 4.7.0
 * @access private
 		return null;
 	}
 }
 /**
-* 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
 *
 * @since 4.7.0
 * @access private

changeset 21	48c4eec2b7e6
parent 19	3d72ae0968f4
child 22	8c2e4d02f4ef