Docs: Improve documentation for `WP_Http` per the documentation standards.
Props hareesh-pillai, adnan.limdi, isabel_brison. Fixes #41880. Built from https://develop.svn.wordpress.org/trunk@46690 git-svn-id: http://core.svn.wordpress.org/trunk@46490 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov
parent
4d8a0a8b33
commit
5fb34a0a1c
|
|
@ -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 ) {
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
*
|
||||
* @global string $wp_version
|
||||
*/
|
||||
$wp_version = '5.4-alpha-46689';
|
||||
$wp_version = '5.4-alpha-46690';
|
||||
|
||||
/**
|
||||
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
|
||||
|
|
|
|||
Loading…
Reference in New Issue