Make WordPress Core

Changeset 46690


Ignore:
Timestamp:
11/10/2019 01:17:00 AM (7 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve documentation for WP_Http per the documentation standards.

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/class-http.php

    r46596 r46690  
    287287
    288288                // If we are streaming to a file but no filename was given drop it in the WP temp dir
    289                 // and pick its name using the basename of the $url
     289                // and pick its name using the basename of the $url.
    290290                if ( $parsed_args['stream'] ) {
    291291                        if ( empty( $parsed_args['filename'] ) ) {
    … …  
    293293                        }
    294294
    295                         // Force some settings if we are streaming to a file and check for existence and perms of destination directory
     295                        // Force some settings if we are streaming to a file and check for existence
     296                        // and perms of destination directory.
    296297                        $parsed_args['blocking'] = true;
    297298                        if ( ! wp_is_writable( dirname( $parsed_args['filename'] ) ) ) {
    … …  
    313314                }
    314315
    315                 // Setup arguments
     316                // Setup arguments.
    316317                $headers = $parsed_args['headers'];
    317318                $data    = $parsed_args['body'];
    … …  
    341342                }
    342343
    343                 // Use byte limit, if we can
     344                // Use byte limit, if we can.
    344345                if ( isset( $parsed_args['limit_response_size'] ) ) {
    345346                        $options['max_bytes'] = $parsed_args['limit_response_size'];
    … …  
    351352                }
    352353
    353                 // SSL certificate handling
     354                // SSL certificate handling.
    354355                if ( ! $parsed_args['sslverify'] ) {
    355356                        $options['verify']     = false;
    … …  
    387388                }
    388389
    389                 // Avoid issues where mbstring.func_overload is enabled
     390                // Avoid issues where mbstring.func_overload is enabled.
    390391                mbstring_binary_safe_encoding();
    391392
    … …  
    393394                        $requests_response = Requests::request( $url, $headers, $data, $type, $options );
    394395
    395                         // Convert the response into an array
     396                        // Convert the response into an array.
    396397                        $http_response = new WP_HTTP_Requests_Response( $requests_response, $parsed_args['filename'] );
    397398                        $response      = $http_response->to_array();
    … …  
    484485         */
    485486        public static function browser_redirect_compatibility( $location, $headers, $data, &$options, $original ) {
    486                 // Browser compat
     487                // Browser compatibility.
    487488                if ( $original->status_code === 302 ) {
    488489                        $options['type'] = Requests::GET;
    … …  
    495496         * @since 4.7.5
    496497         *
    497          * @throws Requests_Exception On unsuccessful URL validation
     498         * @throws Requests_Exception On unsuccessful URL validation.
    498499         * @param string $location URL to redirect to.
    499500         */
    … …  
    509510         * @since 3.2.0
    510511         *
    511          * @param array $args Request arguments
    512          * @param string $url URL to Request
    513          *
    514          * @return string|false Class name for the first transport that claims to support the request. False if no transport claims to support the request.
     512         * @param array $args Request arguments.
     513         * @param string $url URL to Request.
     514         *
     515         * @return string|false Class name for the first transport that claims to support the request.
     516         *                      False if no transport claims to support the request.
    515517         */
    516518        public function _get_first_available_transport( $args, $url = null ) {
    … …  
    559561         * @see WP_Http::request()
    560562         *
    561          * @param string $url URL to Request
    562          * @param array $args Request arguments
    563          * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
     563         * @param string $url URL to Request.
     564         * @param array $args Request arguments.
     565         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
     566         *                        A WP_Error instance upon error.
    564567         */
    565568        private function _dispatch_request( $url, $args ) {
    … …  
    598601         * @param string       $url  The request URL.
    599602         * @param string|array $args Optional. Override the defaults.
    600          * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
     603         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
     604         *                        A WP_Error instance upon error.
    601605         */
    602606        public function post( $url, $args = array() ) {
    … …  
    615619         * @param string $url The request URL.
    616620         * @param string|array $args Optional. Override the defaults.
    617          * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
     621         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
     622         *                        A WP_Error instance upon error.
    618623         */
    619624        public function get( $url, $args = array() ) {
    … …  
    632637         * @param string $url The request URL.
    633638         * @param string|array $args Optional. Override the defaults.
    634          * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
     639         * @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
     640         *                        A WP_Error instance upon error.
    635641         */
    636642        public function head( $url, $args = array() ) {
    … …  
    645651         * @since 2.7.0
    646652         *
    647          * @param string $strResponse The full response string
     653         * @param string $strResponse The full response string.
    648654         * @return array Array with 'headers' and 'body' keys.
    649655         */
    … …  
    660666         * Transform header string into an array.
    661667         *
    662          * If an array is given then it is assumed to be raw header data with numeric keys with the
     668         * If an array is given, then it is assumed to be raw header data with numeric keys with the
    663669         * headers as the values. No headers must be passed that were already processed.
    664670         *
    … …  
    666672         *
    667673         * @param string|array $headers
    668          * @param string $url The URL that was requested
     674         * @param string $url The URL that was requested.
    669675         * @return array Processed string headers. If duplicate headers are encountered,
    670          *                  Then a numbered array is returned as the value of that header-key.
     676         *               then a numbered array is returned as the value of that header-key.
    671677         */
    672678        public static function processHeaders( $headers, $url = '' ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.MethodNameInvalid
    … …  
    732738                }
    733739
    734                 // Cast the Response Code to an int
     740                // Cast the Response Code to an int.
    735741                $response['code'] = intval( $response['code'] );
    736742
    … …  
    786792         * @since 2.7.0
    787793         *
    788          * @param string $body Body content
     794         * @param string $body Body content.
    789795         * @return string Chunked decoded body on success or raw body on failure.
    790796         */
    … …  
    919925         * @since 3.4.0
    920926         *
    921          * @param string $maybe_relative_path The URL which might be relative
    922          * @param string $url                 The URL which $maybe_relative_path is relative to
     927         * @param string $maybe_relative_path The URL which might be relative.
     928         * @param string $url                 The URL which $maybe_relative_path is relative to.
    923929         * @return string An Absolute URL, in a failure condition where the URL cannot be parsed, the relative URL will be returned.
    924930         */
    … …  
    945951                $absolute_path = $url_parts['scheme'] . '://';
    946952
    947                 // 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
     953                // Schemeless URLs will make it this far, so we check for a host in the relative url
     954                // and convert it to a protocol-url
    948955                if ( isset( $relative_url_parts['host'] ) ) {
    949956                        $absolute_path .= $relative_url_parts['host'];
    … …  
    965972                        $path = $relative_url_parts['path'];
    966973
    967                         // Else it's a relative path.
     974                // Else it's a relative path.
    968975                } elseif ( ! empty( $relative_url_parts['path'] ) ) {
    969976                        // Strip off any file components from the absolute path.
    … …  
    10531060         * an IP address.
    10541061         *
    1055          * @link http://home.deds.nl/~aeron/regex/ for IPv6 regex
     1062         * @link http://home.deds.nl/~aeron/regex/ for IPv6 regex.
    10561063         *
    10571064         * @since 3.7.0
    10581065         *
    1059          * @param string $maybe_ip A suspected IP address
     1066         * @param string $maybe_ip A suspected IP address.
    10601067         * @return integer|bool Upon success, '4' or '6' to represent a IPv4 or IPv6 address, false upon failure
    10611068         */
Note: See TracChangeset for help on using the changeset viewer.