sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: Improve documentation for WP_Http per the documentation standards.

Browse Source 
Props hareesh-pillai, adnan.limdi, isabel_brison.
Fixes #41880.

git-svn-id: https://develop.svn.wordpress.org/trunk@46690 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2019-11-10 01:17:00 +00:00
parent 00aff3a706
commit 99132f8abc
1 changed files with 37 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
src/wp-includes/class-http.php
View File

@ -286,13 +286,14 @@ class WP_Http {
}
// If we are streaming to a file but no filename was given drop it in the WP temp dir
// and pick its name using the basename of the $url
// and pick its name using the basename of the $url.
if ( $parsed_args['stream'] ) {
if ( empty( $parsed_args['filename'] ) ) {
$parsed_args['filename'] = get_temp_dir() . basename( $url );
}
// Force some settings if we are streaming to a file and check for existence and perms of destination directory
// Force some settings if we are streaming to a file and check for existence
// and perms of destination directory.
$parsed_args['blocking'] = true;
if ( ! wp_is_writable( dirname( $parsed_args['filename'] ) ) ) {
$response = new WP_Error( 'http_request_failed', __( 'Destination directory for file streaming does not exist or is not writable.' ) );
@ -312,7 +313,7 @@ class WP_Http {
$parsed_args['headers'] = $processedHeaders['headers'];
}
// Setup arguments
// Setup arguments.
$headers = $parsed_args['headers'];
$data = $parsed_args['body'];
$type = $parsed_args['method'];
@ -340,7 +341,7 @@ class WP_Http {
$options['redirects'] = $parsed_args['redirection'];
}
// Use byte limit, if we can
// Use byte limit, if we can.
if ( isset( $parsed_args['limit_response_size'] ) ) {
$options['max_bytes'] = $parsed_args['limit_response_size'];
}
@ -350,7 +351,7 @@ class WP_Http {
$options['cookies'] = WP_Http::normalize_cookies( $parsed_args['cookies'] );
}
// SSL certificate handling
// SSL certificate handling.
if ( ! $parsed_args['sslverify'] ) {
$options['verify'] = false;
$options['verifyname'] = false;
@ -386,13 +387,13 @@ class WP_Http {
}
}
// Avoid issues where mbstring.func_overload is enabled
// Avoid issues where mbstring.func_overload is enabled.
mbstring_binary_safe_encoding();
try {
$requests_response = Requests::request( $url, $headers, $data, $type, $options );
// Convert the response into an array
// Convert the response into an array.
$http_response = new WP_HTTP_Requests_Response( $requests_response, $parsed_args['filename'] );
$response = $http_response->to_array();
@ -483,7 +484,7 @@ class WP_Http {
* @param Requests_Response $original Response object.
*/
public static function browser_redirect_compatibility( $location, $headers, $data, &$options, $original ) {
// Browser compat
// Browser compatibility.
if ( $original->status_code === 302 ) {
$options['type'] = Requests::GET;
}
@ -494,7 +495,7 @@ class WP_Http {
*
* @since 4.7.5
*
* @throws Requests_Exception On unsuccessful URL validation
* @throws Requests_Exception On unsuccessful URL validation.
* @param string $location URL to redirect to.
*/
public static function validate_redirects( $location ) {
@ -508,10 +509,11 @@ class WP_Http {
*
* @since 3.2.0
*
* @param array $args Request arguments
* @param string $url URL to Request
* @param array $args Request arguments.
* @param string $url URL to Request.
*
* @return string|false Class name for the first transport that claims to support the request. False if no transport claims to support the request.
* @return string|false Class name for the first transport that claims to support the request.
* False if no transport claims to support the request.
*/
public function _get_first_available_transport( $args, $url = null ) {
$transports = array( 'curl', 'streams' );
@ -558,9 +560,10 @@ class WP_Http {
* @deprecated 5.1.0 Use WP_Http::request()
* @see WP_Http::request()
*
* @param string $url URL to Request
* @param array $args Request arguments
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
* @param string $url URL to Request.
* @param array $args Request arguments.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
*/
private function _dispatch_request( $url, $args ) {
static $transports = array();
@ -597,7 +600,8 @@ class WP_Http {
*
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
*/
public function post( $url, $args = array() ) {
$defaults = array( 'method' => 'POST' );
@ -614,7 +618,8 @@ class WP_Http {
*
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
*/
public function get( $url, $args = array() ) {
$defaults = array( 'method' => 'GET' );
@ -631,7 +636,8 @@ class WP_Http {
*
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
*/
public function head( $url, $args = array() ) {
$defaults = array( 'method' => 'HEAD' );
@ -644,7 +650,7 @@ class WP_Http {
*
* @since 2.7.0
*
* @param string $strResponse The full response string
* @param string $strResponse The full response string.
* @return array Array with 'headers' and 'body' keys.
*/
public static function processResponse( $strResponse ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
@ -659,15 +665,15 @@ class WP_Http {
/**
* Transform header string into an array.
*
* If an array is given then it is assumed to be raw header data with numeric keys with the
* If an array is given, then it is assumed to be raw header data with numeric keys with the
* headers as the values. No headers must be passed that were already processed.
*
* @since 2.7.0
*
* @param string|array $headers
* @param string $url The URL that was requested
* @param string $url The URL that was requested.
* @return array Processed string headers. If duplicate headers are encountered,
* Then a numbered array is returned as the value of that header-key.
* then a numbered array is returned as the value of that header-key.
*/
public static function processHeaders( $headers, $url = '' ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
// Split headers, one per array element.
@ -731,7 +737,7 @@ class WP_Http {
}
}
// Cast the Response Code to an int
// Cast the Response Code to an int.
$response['code'] = intval( $response['code'] );
return array(
@ -785,7 +791,7 @@ class WP_Http {
*
* @since 2.7.0
*
* @param string $body Body content
* @param string $body Body content.
* @return string Chunked decoded body on success or raw body on failure.
*/
public static function chunkTransferDecode( $body ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
@ -918,8 +924,8 @@ class WP_Http {
*
* @since 3.4.0
*
* @param string $maybe_relative_path The URL which might be relative
* @param string $url The URL which $maybe_relative_path is relative to
* @param string $maybe_relative_path The URL which might be relative.
* @param string $url The URL which $maybe_relative_path is relative to.
* @return string An Absolute URL, in a failure condition where the URL cannot be parsed, the relative URL will be returned.
*/
public static function make_absolute_url( $maybe_relative_path, $url ) {
@ -944,7 +950,8 @@ class WP_Http {
$absolute_path = $url_parts['scheme'] . '://';
// Schemeless URL's will make it this far, so we check for a host in the relative url and convert it to a protocol-url
// Schemeless URLs will make it this far, so we check for a host in the relative url
// and convert it to a protocol-url
if ( isset( $relative_url_parts['host'] ) ) {
$absolute_path .= $relative_url_parts['host'];
if ( isset( $relative_url_parts['port'] ) ) {
@ -964,7 +971,7 @@ class WP_Http {
if ( ! empty( $relative_url_parts['path'] ) && '/' == $relative_url_parts['path'][0] ) {
$path = $relative_url_parts['path'];
// Else it's a relative path.
// Else it's a relative path.
} elseif ( ! empty( $relative_url_parts['path'] ) ) {
// Strip off any file components from the absolute path.
$path = substr( $path, 0, strrpos( $path, '/' ) + 1 );
@ -1052,11 +1059,11 @@ class WP_Http {
* This does not verify if the IP is a valid IP, only that it appears to be
* an IP address.
*
* @link http://home.deds.nl/~aeron/regex/ for IPv6 regex
* @link http://home.deds.nl/~aeron/regex/ for IPv6 regex.
*
* @since 3.7.0
*
* @param string $maybe_ip A suspected IP address
* @param string $maybe_ip A suspected IP address.
* @return integer|bool Upon success, '4' or '6' to represent a IPv4 or IPv6 address, false upon failure
*/
public static function is_ip_address( $maybe_ip ) {