WordPress.org

Make WordPress Core

Changeset 27049


Ignore:
Timestamp:
01/28/2014 08:25:00 AM (8 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/class-http.php.

Props kraftbj for the initial patches. Props kpdesign, DrewAPicture.
Fixes #26049.

File:
1 edited

Legend:

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

    r26868 r27049  
    7070        $defaults = array(
    7171            'method' => 'GET',
    72             'timeout' => apply_filters( 'http_request_timeout', 5),
    73             'redirection' => apply_filters( 'http_request_redirection_count', 5),
    74             'httpversion' => apply_filters( 'http_request_version', '1.0'),
     72            /**
     73             * Filter the timeout value for an HTTP request.
     74             *
     75             * @since 2.7.0
     76             *
     77             * @param int $timeout_value Time in seconds until a request times out.
     78             *                           Default 5.
     79             */
     80            'timeout' => apply_filters( 'http_request_timeout', 5 ),
     81            /**
     82             * Filter the number of redirects allowed during an HTTP request.
     83             *
     84             * @since 2.7.0
     85             *
     86             * @param int $redirect_count Number of redirects allowed. Default 5.
     87             */
     88            'redirection' => apply_filters( 'http_request_redirection_count', 5 ),
     89            /**
     90             * Filter the version of the HTTP protocol used in a request.
     91             *
     92             * @since 2.7.0
     93             *
     94             * @param string $version Version of HTTP used. Accepts '1.0' and '1.1'.
     95             *                        Default '1.0'.
     96             */
     97            'httpversion' => apply_filters( 'http_request_version', '1.0' ),
     98            /**
     99             * Filter the user agent value sent with an HTTP request.
     100             *
     101             * @since 2.7.0
     102             *
     103             * @param string $user_agent WordPress user agent string.
     104             */
    75105            'user-agent' => apply_filters( 'http_headers_useragent', 'WordPress/' . $wp_version . '; ' . get_bloginfo( 'url' ) ),
     106            /**
     107             * Filter whether to pass URLs through wp_http_validate_url() in an HTTP request.
     108             *
     109             * @since 3.6.0
     110             *
     111             * @param bool $pass_url Whether to pass URLs through wp_http_validate_url().
     112             *                       Default false.
     113             */
    76114            'reject_unsafe_urls' => apply_filters( 'http_request_reject_unsafe_urls', false ),
    77115            'blocking' => true,
     
    96134
    97135        $r = wp_parse_args( $args, $defaults );
     136        /**
     137         * Filter the arguments used in an HTTP request.
     138         *
     139         * @since 2.7.0
     140         *
     141         * @param array  $r   An array of HTTP request arguments.
     142         * @param string $url The request URI resource.
     143         */
    98144        $r = apply_filters( 'http_request_args', $r, $url );
    99145
     
    102148            $r['_redirection'] = $r['redirection'];
    103149
    104         // Allow plugins to short-circuit the request
     150        /**
     151         * Filter whether to preempt an HTTP request's return.
     152         *
     153         * Returning a truthy value to the filter will short-circuit
     154         * the HTTP request and return early with that value.
     155         *
     156         * @since 2.9.0
     157         *
     158         * @param bool   $preempt Whether to preempt an HTTP request return. Default false.
     159         * @param array  $r       HTTP request arguments.
     160         * @param string $url     The request URI resource.
     161         */
    105162        $pre = apply_filters( 'pre_http_request', false, $r, $url );
    106163        if ( false !== $pre )
     
    222279     */
    223280    public function _get_first_available_transport( $args, $url = null ) {
     281        /**
     282         * Filter which HTTP transports are available and in what order.
     283         *
     284         * @since 3.7.0
     285         *
     286         * @param array  $value Array of HTTP transports to check. Default array contains
     287         *                      'curl', and 'streams', in that order.
     288         * @param array  $args  HTTP request arguments.
     289         * @param string $url   The URL to request.
     290         */
    224291        $request_order = apply_filters( 'http_api_transports', array( 'curl', 'streams' ), $args, $url );
    225292
     
    266333        $response = $transports[$class]->request( $url, $args );
    267334
     335        /**
     336         * Fires after an HTTP API response is received and before the response is returned.
     337         *
     338         * @since 2.8.0
     339         *
     340         * @param mixed  $response HTTP Response or WP_Error object.
     341         * @param string $context  Context under which the hook is fired.
     342         * @param string $class    HTTP transport used.
     343         * @param array  $args     HTTP request arguments.
     344         * @param string $url      The request URL.
     345         */
    268346        do_action( 'http_api_debug', $response, 'response', $class, $args, $url );
    269347
     
    271349            return $response;
    272350
     351        /**
     352         * Filter the HTTP API response immediately before the response is returned.
     353         *
     354         * @since 2.9.0
     355         *
     356         * @param array|obj $response HTTP Response.
     357         * @param array     $args     HTTP request arguments.
     358         * @param string    $url      The request URL.
     359         */
    273360        return apply_filters( 'http_response', $response, $args, $url );
    274361    }
     
    282369     * @since 2.7.0
    283370     *
    284      * @param string $url URI resource.
    285      * @param str|array $args Optional. Override the defaults.
     371     * @param string       $url URI resource.
     372     * @param string|array $args Optional. Override the defaults.
    286373     * @return array|object Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
    287374     */
     
    517604
    518605        // Don't block requests back to ourselves by default
    519         if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] )
    520             return apply_filters('block_local_requests', false);
     606        if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] ) {
     607            /**
     608             * Filter whether to block local requests through the proxy.
     609             *
     610             * @since 2.8.0
     611             *
     612             * @param bool $block Whether to block local requests through proxy.
     613             *                    Default false.
     614             */
     615            return apply_filters( 'block_local_requests', false );
     616        }
    521617
    522618        if ( !defined('WP_ACCESSIBLE_HOSTS') )
     
    743839        $is_local = isset( $r['local'] ) && $r['local'];
    744840        $ssl_verify = isset( $r['sslverify'] ) && $r['sslverify'];
    745         if ( $is_local )
     841        if ( $is_local ) {
     842            /**
     843             * Filter whether SSL should be verified for local requests.
     844             *
     845             * @since 2.8.0
     846             *
     847             * @param bool $ssl_verify Whether to verify the SSL connection. Default true.
     848             */
    746849            $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify );
    747         elseif ( ! $is_local )
     850        } elseif ( ! $is_local ) {
     851            /**
     852             * Filter whether SSL should be verified for non-local requests.
     853             *
     854             * @since 2.8.0
     855             *
     856             * @param bool $ssl_verify Whether to verify the SSL connection. Default true.
     857             */
    748858            $ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify );
     859        }
    749860
    750861        $proxy = new WP_HTTP_Proxy();
     
    10051116
    10061117    /**
    1007      * Whether this class can be used for retrieving an URL.
     1118     * Whether this class can be used for retrieving a URL.
    10081119     *
    10091120     * @static
     
    10271138        }
    10281139
     1140        /**
     1141         * Filter whether streams can be used as a transport for retrieving a URL.
     1142         *
     1143         * @since 2.7.0
     1144         *
     1145         * @param bool  $use_class Whether the class can be used. Default true.
     1146         * @param array $args      Request arguments.
     1147         */
    10291148        return apply_filters( 'use_streams_transport', true, $args );
    10301149    }
     
    11461265        $is_local = isset($r['local']) && $r['local'];
    11471266        $ssl_verify = isset($r['sslverify']) && $r['sslverify'];
    1148         if ( $is_local )
    1149             $ssl_verify = apply_filters('https_local_ssl_verify', $ssl_verify);
    1150         elseif ( ! $is_local )
    1151             $ssl_verify = apply_filters('https_ssl_verify', $ssl_verify);
     1267        if ( $is_local ) {
     1268            /** This filter is documented in wp-includes/class-http.php */
     1269            $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify );
     1270        } elseif ( ! $is_local ) {
     1271            /** This filter is documented in wp-includes/class-http.php */
     1272            $ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify );
     1273        }
    11521274
    11531275        // CURLOPT_TIMEOUT and CURLOPT_CONNECTTIMEOUT expect integers. Have to use ceil since
     
    12261348            curl_setopt( $handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1 );
    12271349
    1228         // Cookies are not handled by the HTTP API currently. Allow for plugin authors to handle it
    1229         // themselves... Although, it is somewhat pointless without some reference.
     1350        /**
     1351         * Fires before the cURL request is executed.
     1352         *
     1353         * Cookies are not currently handled by the HTTP API. This action allows
     1354         * plugins to handle cookies themselves.
     1355         *
     1356         * @since 2.8.0
     1357         *
     1358         * @param array $handle cURL options set using curl_setopt().
     1359         */
    12301360        do_action_ref_array( 'http_api_curl', array(&$handle) );
    12311361
     
    13621492        }
    13631493
     1494        /**
     1495         * Filter whether cURL can be used as a transport for retrieving a URL.
     1496         *
     1497         * @since 2.7.0
     1498         *
     1499         * @param bool  $use_class Whether the class can be used. Default true.
     1500         * @param array $args      An array of request arguments.
     1501         */
    13641502        return apply_filters( 'use_curl_transport', true, $args );
    13651503    }
     
    15301668        $home = parse_url( get_option('siteurl') );
    15311669
     1670        /**
     1671         * Filter whether to preempt sending the request through the proxy server.
     1672         *
     1673         * Returning false will bypass the proxy; returning true will send
     1674         * the request through the proxy. Returning null bypasses the filter.
     1675         *
     1676         * @since 3.5.0
     1677         *
     1678         * @param null   $override Whether to override the request result. Default null.
     1679         * @param string $uri      URL to check.
     1680         * @param array  $check    Associative array result of parsing the URI.
     1681         * @param array  $home     Associative array result of parsing the site URL.
     1682         */
    15321683        $result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home );
    15331684        if ( ! is_null( $result ) )
     
    17441895            return '';
    17451896
     1897        /**
     1898         * Filter the header-encoded cookie value.
     1899         *
     1900         * @since 3.4.0
     1901         *
     1902         * @param string $value The cookie value.
     1903         * @param string $name  The cookie name.
     1904         */
    17461905        return $this->name . '=' . apply_filters( 'wp_http_cookie_value', $this->value, $this->name );
    17471906    }
     
    19052064        }
    19062065
     2066        /**
     2067         * Filter the allowed encoding types.
     2068         *
     2069         * @since 3.6.0
     2070         *
     2071         * @param array  $type Encoding types allowed. Accepts 'gzinflate',
     2072         *                     'gzuncompress', 'gzdecode'.
     2073         * @param string $url  URL of the HTTP request.
     2074         * @param array  $args HTTP request arguments.
     2075         */
    19072076        $type = apply_filters( 'wp_http_accept_encoding', $type, $url, $args );
    19082077
Note: See TracChangeset for help on using the changeset viewer.