From 99132f8abc9d5a1858dc3d9cb628e30cf16d13c2 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Sun, 10 Nov 2019 01:17:00 +0000 Subject: [PATCH] Docs: Improve documentation for `WP_Http` per the documentation standards. Props hareesh-pillai, adnan.limdi, isabel_brison. Fixes #41880. git-svn-id: https://develop.svn.wordpress.org/trunk@46690 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-http.php | 67 +++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 30 deletions(-) diff --git a/src/wp-includes/class-http.php b/src/wp-includes/class-http.php index 259b3747e3..c47995d2aa 100644 --- a/src/wp-includes/class-http.php +++ b/src/wp-includes/class-http.php @@ -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 ) {