Index: src/wp-includes/class-http.php =================================================================== --- src/wp-includes/class-http.php (revision 26931) +++ src/wp-includes/class-http.php (working copy) @@ -69,10 +69,45 @@ $defaults = array( 'method' => 'GET', - 'timeout' => apply_filters( 'http_request_timeout', 5), - 'redirection' => apply_filters( 'http_request_redirection_count', 5), - 'httpversion' => apply_filters( 'http_request_version', '1.0'), + /** + * Filter the timeout value for the HTTP request. + * + * @since 2.7.0 + * + * @param int $timeout_value Time in seconds until a request times out. + */ + 'timeout' => apply_filters( 'http_request_timeout', 5 ), + /** + * Filter the number of redirects allowed during the HTTP request. + * + * @since 2.7.0 + * + * @param int $redirect_count Number of redirects allowed. + */ + 'redirection' => apply_filters( 'http_request_redirection_count', 5 ), + /** + * Filter the version of the HTTP protocol used in the request. + * + * @since 2.7.0 + * + * @param string $version Version of HTTP used. Accepts '1.0' and '1.1'. + */ + 'httpversion' => apply_filters( 'http_request_version', '1.0' ), + /** + * Filter the user agent value sent with the HTTP request. + * + * @since 2.7.0 + * + * @param string $user_agent User agent string. + */ 'user-agent' => apply_filters( 'http_headers_useragent', 'WordPress/' . $wp_version . '; ' . get_bloginfo( 'url' ) ), + /** + * Filter whether to pass URLs through wp_http_validate_url(). + * + * @since 3.6.0 + * + * @param bool $bool Whether to pass URL through wp_http_validate_url(). + */ 'reject_unsafe_urls' => apply_filters( 'http_request_reject_unsafe_urls', false ), 'blocking' => true, 'headers' => array(), @@ -95,6 +130,14 @@ $defaults['redirection'] = 0; $r = wp_parse_args( $args, $defaults ); + /** + * Filter the arguments used in an HTTP request. + * + * @since 2.7.0 + * + * @param array $r The default values parsed with arguments passed from HEAD check. + * @param string $url URI resource. + */ $r = apply_filters( 'http_request_args', $r, $url ); // The transports decrement this, store a copy of the original value for loop purposes. @@ -101,7 +144,16 @@ if ( ! isset( $r['_redirection'] ) ) $r['_redirection'] = $r['redirection']; - // Allow plugins to short-circuit the request + /** + * Filter the arguments for the HTTP request. + * + * @since 2.9.0 + * + * @param bool $bool Whether to use arguments from a plugin without + * further operations. Default false. + * @param array $r HTTP request options. + * @param type $url URI Resource. + */ $pre = apply_filters( 'pre_http_request', false, $r, $url ); if ( false !== $pre ) return $pre; @@ -221,6 +273,16 @@ * @return string|bool 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 ) { + /** + * Filter the order HTTP transports are checked. + * + * @since 3.7.0 + * + * @param array $value Establishes transports to check, in order. + * Default 'curl', 'streams'. + * @param array $args Request arguments. + * @param string $url URL to request. + */ $request_order = apply_filters( 'http_api_transports', array( 'curl', 'streams' ), $args, $url ); // Loop over each transport on each HTTP request looking for one which will serve this request's needs @@ -265,11 +327,30 @@ $response = $transports[$class]->request( $url, $args ); + /** + * Fires after an HTTP API response is received and before the response is returned. + * + * @since 2.8.0 + * + * @param array|obj $response HTTP Response or WP_Error object. + * @param string $class HTTP transport used. + * @param array $args Requested arguments. + * @param string $url Requested URL. + */ do_action( 'http_api_debug', $response, 'response', $class, $args, $url ); if ( is_wp_error( $response ) ) return $response; + /** + * Filter the HTTP API response immediately before the response is returned. + * + * @since 2.9.0 + * + * @param array|obj $response HTTP Response. + * @param array $args Requested arguments. + * @param string $url Requested URL. + */ return apply_filters( 'http_response', $response, $args, $url ); } @@ -517,7 +598,14 @@ // Don't block requests back to ourselves by default if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] ) - return apply_filters('block_local_requests', false); + /** + * Filter whether to block local requests through the proxy. + * + * @since 2.8.0 + * + * @param bool $bool Whether to block local requests through proxy. Default false. + */ + return apply_filters( 'block_local_requests', false ); if ( !defined('WP_ACCESSIBLE_HOSTS') ) return true; @@ -743,8 +831,22 @@ $is_local = isset( $r['local'] ) && $r['local']; $ssl_verify = isset( $r['sslverify'] ) && $r['sslverify']; if ( $is_local ) + /** + * Filter whether SSL should be verified for local requests. + * + * @since 2.8.0 + * + * @param bool $ssl_verify Verify the SSL connection. + */ $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify ); elseif ( ! $is_local ) + /** + * Filter whether SSL should be verified for non-local requests. + * + * @since 2.8.0 + * + * @param bool $ssl_verify Verify the SSL connection. + */ $ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify ); $proxy = new WP_HTTP_Proxy(); @@ -1026,6 +1128,14 @@ return false; } + /** + * Filter whether the WP_Http_Streams class can be used for retrieving a URL. + * + * @since 2.7.0 + * + * @param bool $bool Whether the class can be used. Default true. + * @param array $args Request arguments. + */ return apply_filters( 'use_streams_transport', true, $args ); } } @@ -1146,9 +1256,11 @@ $is_local = isset($r['local']) && $r['local']; $ssl_verify = isset($r['sslverify']) && $r['sslverify']; if ( $is_local ) - $ssl_verify = apply_filters('https_local_ssl_verify', $ssl_verify); + /** This filter is documented in wp-includes/class-http.php */ + $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify ); elseif ( ! $is_local ) - $ssl_verify = apply_filters('https_ssl_verify', $ssl_verify); + /** This filter is documented in wp-includes/class-http.php */ + $ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify ); // CURLOPT_TIMEOUT and CURLOPT_CONNECTTIMEOUT expect integers. Have to use ceil since // a value of 0 will allow an unlimited timeout. @@ -1225,8 +1337,16 @@ else curl_setopt( $handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1 ); - // Cookies are not handled by the HTTP API currently. Allow for plugin authors to handle it - // themselves... Although, it is somewhat pointless without some reference. + /** + * Fires before the cURL process is executed. + * + * Cookies are not currently handled by the HTTP API. This action allows + * plugins to handle cookies themselves. + * + * @since 2.8.0 + * + * @param array $handle cURL options set using curl_setopt. + */ do_action_ref_array( 'http_api_curl', array(&$handle) ); // We don't need to return the body, so don't. Just execute request and return. @@ -1361,6 +1481,14 @@ return false; } + /** + * Filter whether the WP_Http_Curl class can be used for retrieving a URL. + * + * @since 2.7.0 + * + * @param bool $bool Whether the class can be used. Default true. + * @param array $args An array of request arguments. + */ return apply_filters( 'use_curl_transport', true, $args ); } } @@ -1529,6 +1657,21 @@ $home = parse_url( get_option('siteurl') ); + /** + * Filter whether to force send_through_proxy. + * + * This filter allows a plugin to preempt the return value of + * WP_HTTP_Proxy::send_through_proxy(). + * + * @since 3.5.0 + * + * @param null $override_result Whether to override the result. + * Return true to send through the proxy, + * false to bypass the proxy. Default null. + * @param string $uri URL to check. + * @param array $check Associative array result of parse_url($uri). + * @param array $home Associative array result of parse_url() of the siteurl. + */ $result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home ); if ( ! is_null( $result ) ) return $result; @@ -1743,6 +1886,14 @@ if ( ! isset( $this->name ) || ! isset( $this->value ) ) return ''; + /** + * Filter the header-encoded cookie value. + * + * @since 3.4.0 + * + * @param string $value The cookie value. + * @param string $name The cookie name. + */ return $this->name . '=' . apply_filters( 'wp_http_cookie_value', $this->value, $this->name ); } @@ -1904,6 +2055,16 @@ $type[] = 'gzip;q=0.5'; } + /** + * Filter the allowed encoding types. + * + * @since 3.6.0 + * + * @param array $type Encoding types allowed. Accepts 'gzinflate', + * 'gzuncompress', 'gzdecode'. + * @param string $url URL of the HTTP request. + * @param array $args HTTP request arguments. + */ $type = apply_filters( 'wp_http_accept_encoding', $type, $url, $args ); return implode(', ', $type);