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 // 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 ( $parsed_args['stream'] ) {
if ( empty( $parsed_args['filename'] ) ) { if ( empty( $parsed_args['filename'] ) ) {
$parsed_args['filename'] = get_temp_dir() . basename( $url ); $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; $parsed_args['blocking'] = true;
if ( ! wp_is_writable( dirname( $parsed_args['filename'] ) ) ) { 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.' ) ); $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']; $parsed_args['headers'] = $processedHeaders['headers'];
} }
// Setup arguments // Setup arguments.
$headers = $parsed_args['headers']; $headers = $parsed_args['headers'];
$data = $parsed_args['body']; $data = $parsed_args['body'];
$type = $parsed_args['method']; $type = $parsed_args['method'];
@ -340,7 +341,7 @@ class WP_Http {
$options['redirects'] = $parsed_args['redirection']; $options['redirects'] = $parsed_args['redirection'];
} }
// Use byte limit, if we can // Use byte limit, if we can.
if ( isset( $parsed_args['limit_response_size'] ) ) { if ( isset( $parsed_args['limit_response_size'] ) ) {
$options['max_bytes'] = $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'] ); $options['cookies'] = WP_Http::normalize_cookies( $parsed_args['cookies'] );
} }
// SSL certificate handling // SSL certificate handling.
if ( ! $parsed_args['sslverify'] ) { if ( ! $parsed_args['sslverify'] ) {
$options['verify'] = false; $options['verify'] = false;
$options['verifyname'] = 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(); mbstring_binary_safe_encoding();
try { try {
$requests_response = Requests::request( $url, $headers, $data, $type, $options ); $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'] ); $http_response = new WP_HTTP_Requests_Response( $requests_response, $parsed_args['filename'] );
$response = $http_response->to_array(); $response = $http_response->to_array();
@ -483,7 +484,7 @@ class WP_Http {
* @param Requests_Response $original Response object. * @param Requests_Response $original Response object.
*/ */
public static function browser_redirect_compatibility( $location, $headers, $data, &$options, $original ) { public static function browser_redirect_compatibility( $location, $headers, $data, &$options, $original ) {
// Browser compat // Browser compatibility.
if ( $original->status_code === 302 ) { if ( $original->status_code === 302 ) {
$options['type'] = Requests::GET; $options['type'] = Requests::GET;
} }
@ -494,7 +495,7 @@ class WP_Http {
* *
* @since 4.7.5 * @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. * @param string $location URL to redirect to.
*/ */
public static function validate_redirects( $location ) { public static function validate_redirects( $location ) {
@ -508,10 +509,11 @@ class WP_Http {
* *
* @since 3.2.0 * @since 3.2.0
* *
* @param array $args Request arguments * @param array $args Request arguments.
* @param string $url URL to Request * @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 ) { public function _get_first_available_transport( $args, $url = null ) {
$transports = array( 'curl', 'streams' ); $transports = array( 'curl', 'streams' );
@ -558,9 +560,10 @@ class WP_Http {
* @deprecated 5.1.0 Use WP_Http::request() * @deprecated 5.1.0 Use WP_Http::request()
* @see WP_Http::request() * @see WP_Http::request()
* *
* @param string $url URL to Request * @param string $url URL to Request.
* @param array $args Request arguments * @param array $args Request arguments.
* @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.
*/ */
private function _dispatch_request( $url, $args ) { private function _dispatch_request( $url, $args ) {
static $transports = array(); static $transports = array();
@ -597,7 +600,8 @@ class WP_Http {
* *
* @param string $url The request URL. * @param string $url The request URL.
* @param string|array $args Optional. Override the defaults. * @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() ) { public function post( $url, $args = array() ) {
$defaults = array( 'method' => 'POST' ); $defaults = array( 'method' => 'POST' );
@ -614,7 +618,8 @@ class WP_Http {
* *
* @param string $url The request URL. * @param string $url The request URL.
* @param string|array $args Optional. Override the defaults. * @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() ) { public function get( $url, $args = array() ) {
$defaults = array( 'method' => 'GET' ); $defaults = array( 'method' => 'GET' );
@ -631,7 +636,8 @@ class WP_Http {
* *
* @param string $url The request URL. * @param string $url The request URL.
* @param string|array $args Optional. Override the defaults. * @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() ) { public function head( $url, $args = array() ) {
$defaults = array( 'method' => 'HEAD' ); $defaults = array( 'method' => 'HEAD' );
@ -644,7 +650,7 @@ class WP_Http {
* *
* @since 2.7.0 * @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. * @return array Array with 'headers' and 'body' keys.
*/ */
public static function processResponse( $strResponse ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid public static function processResponse( $strResponse ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
@ -659,15 +665,15 @@ class WP_Http {
/** /**
* Transform header string into an array. * 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. * headers as the values. No headers must be passed that were already processed.
* *
* @since 2.7.0 * @since 2.7.0
* *
* @param string|array $headers * @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, * @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 public static function processHeaders( $headers, $url = '' ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
// Split headers, one per array element. // 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'] ); $response['code'] = intval( $response['code'] );
return array( return array(
@ -785,7 +791,7 @@ class WP_Http {
* *
* @since 2.7.0 * @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. * @return string Chunked decoded body on success or raw body on failure.
*/ */
public static function chunkTransferDecode( $body ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid public static function chunkTransferDecode( $body ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
@ -918,8 +924,8 @@ class WP_Http {
* *
* @since 3.4.0 * @since 3.4.0
* *
* @param string $maybe_relative_path The URL which might be relative * @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 $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. * @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 ) { public static function make_absolute_url( $maybe_relative_path, $url ) {
@ -944,7 +950,8 @@ class WP_Http {
$absolute_path = $url_parts['scheme'] . '://'; $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'] ) ) { if ( isset( $relative_url_parts['host'] ) ) {
$absolute_path .= $relative_url_parts['host']; $absolute_path .= $relative_url_parts['host'];
if ( isset( $relative_url_parts['port'] ) ) { if ( isset( $relative_url_parts['port'] ) ) {
@ -964,7 +971,7 @@ class WP_Http {
if ( ! empty( $relative_url_parts['path'] ) && '/' == $relative_url_parts['path'][0] ) { if ( ! empty( $relative_url_parts['path'] ) && '/' == $relative_url_parts['path'][0] ) {
$path = $relative_url_parts['path']; $path = $relative_url_parts['path'];
// Else it's a relative path. // Else it's a relative path.
} elseif ( ! empty( $relative_url_parts['path'] ) ) { } elseif ( ! empty( $relative_url_parts['path'] ) ) {
// Strip off any file components from the absolute path. // Strip off any file components from the absolute path.
$path = substr( $path, 0, strrpos( $path, '/' ) + 1 ); $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 * This does not verify if the IP is a valid IP, only that it appears to be
* an IP address. * 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 * @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 * @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 ) { public static function is_ip_address( $maybe_ip ) {