$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 an HTTP request.
+ *
+ * @since 2.7.0
+ *
+ * @param int $timeout_value Time in seconds until a request times out.
+ * Default 5.
+ */
+ 'timeout' => apply_filters( 'http_request_timeout', 5 ),
+ /**
+ * Filter the number of redirects allowed during an HTTP request.
+ *
+ * @since 2.7.0
+ *
+ * @param int $redirect_count Number of redirects allowed. Default 5.
+ */
+ 'redirection' => apply_filters( 'http_request_redirection_count', 5 ),
+ /**
+ * Filter the version of the HTTP protocol used in a request.
+ *
+ * @since 2.7.0
+ *
+ * @param string $version Version of HTTP used. Accepts '1.0' and '1.1'.
+ * Default '1.0'.
+ */
+ 'httpversion' => apply_filters( 'http_request_version', '1.0' ),
+ /**
+ * Filter the user agent value sent with an HTTP request.
+ *
+ * @since 2.7.0
+ *
+ * @param string $user_agent WordPress 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() in an HTTP request.
+ *
+ * @since 3.6.0
+ *
+ * @param bool $pass_url Whether to pass URLs through wp_http_validate_url().
+ * Default false.
+ */
'reject_unsafe_urls' => apply_filters( 'http_request_reject_unsafe_urls', false ),
'blocking' => true,
'headers' => array(),
$defaults['redirection'] = 0;
$r = wp_parse_args( $args, $defaults );
+ /**
+ * Filter the arguments used in an HTTP request.
+ *
+ * @since 2.7.0
+ *
+ * @param array $r An array of HTTP request arguments.
+ * @param string $url The request URI resource.
+ */
$r = apply_filters( 'http_request_args', $r, $url );
// The transports decrement this, store a copy of the original value for loop purposes.
if ( ! isset( $r['_redirection'] ) )
$r['_redirection'] = $r['redirection'];
- // Allow plugins to short-circuit the request
+ /**
+ * Filter whether to preempt an HTTP request's return.
+ *
+ * Returning a truthy value to the filter will short-circuit
+ * the HTTP request and return early with that value.
+ *
+ * @since 2.9.0
+ *
+ * @param bool $preempt Whether to preempt an HTTP request return. Default false.
+ * @param array $r HTTP request arguments.
+ * @param string $url The request URI resource.
+ */
$pre = apply_filters( 'pre_http_request', false, $r, $url );
if ( false !== $pre )
return $pre;
* @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 which HTTP transports are available and in what order.
+ *
+ * @since 3.7.0
+ *
+ * @param array $value Array of HTTP transports to check. Default array contains
+ * 'curl', and 'streams', in that order.
+ * @param array $args HTTP request arguments.
+ * @param string $url The 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
$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 mixed $response HTTP Response or WP_Error object.
+ * @param string $context Context under which the hook is fired.
+ * @param string $class HTTP transport used.
+ * @param array $args HTTP request arguments.
+ * @param string $url The request 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 HTTP request arguments.
+ * @param string $url The request URL.
+ */
return apply_filters( 'http_response', $response, $args, $url );
}
* @access public
* @since 2.7.0
*
- * @param string $url URI resource.
- * @param str|array $args Optional. Override the defaults.
+ * @param string $url URI resource.
+ * @param string|array $args Optional. Override the defaults.
* @return array|object Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
*/
function post($url, $args = array()) {
$home = parse_url( get_option('siteurl') );
// Don't block requests back to ourselves by default
- if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] )
- return apply_filters('block_local_requests', false);
+ if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] ) {
+ /**
+ * Filter whether to block local requests through the proxy.
+ *
+ * @since 2.8.0
+ *
+ * @param bool $block Whether to block local requests through proxy.
+ * Default false.
+ */
+ return apply_filters( 'block_local_requests', false );
+ }
if ( !defined('WP_ACCESSIBLE_HOSTS') )
return true;
/**
* HTTP request method uses PHP Streams to retrieve the url.
*
- * @package WordPress
- * @subpackage HTTP
- *
* @since 2.7.0
* @since 3.7.0 Combined with the fsockopen transport and switched to stream_socket_client().
*/
$is_local = isset( $r['local'] ) && $r['local'];
$ssl_verify = isset( $r['sslverify'] ) && $r['sslverify'];
- if ( $is_local )
+ if ( $is_local ) {
+ /**
+ * Filter whether SSL should be verified for local requests.
+ *
+ * @since 2.8.0
+ *
+ * @param bool $ssl_verify Whether to verify the SSL connection. Default true.
+ */
$ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify );
- elseif ( ! $is_local )
+ } elseif ( ! $is_local ) {
+ /**
+ * Filter whether SSL should be verified for non-local requests.
+ *
+ * @since 2.8.0
+ *
+ * @param bool $ssl_verify Whether to verify the SSL connection. Default true.
+ */
$ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify );
+ }
$proxy = new WP_HTTP_Proxy();
}
/**
- * Whether this class can be used for retrieving an URL.
+ * Whether this class can be used for retrieving a URL.
*
* @static
* @access public
return false;
}
+ /**
+ * Filter whether streams can be used as a transport for retrieving a URL.
+ *
+ * @since 2.7.0
+ *
+ * @param bool $use_class Whether the class can be used. Default true.
+ * @param array $args Request arguments.
+ */
return apply_filters( 'use_streams_transport', true, $args );
}
}
*
* @see WP_HTTP::request
*
- * @package WordPress
- * @subpackage HTTP
- *
* @since 2.7.0
* @deprecated 3.7.0 Please use WP_HTTP::request() directly
*/
private $body = '';
/**
- * The maximum amount of data to recieve from the remote server
+ * The maximum amount of data to receive from the remote server.
*
* @since 3.6.0
* @access private
$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);
- elseif ( ! $is_local )
- $ssl_verify = apply_filters('https_ssl_verify', $ssl_verify);
+ if ( $is_local ) {
+ /** This filter is documented in wp-includes/class-http.php */
+ $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify );
+ } elseif ( ! $is_local ) {
+ /** 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.
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.
- do_action_ref_array( 'http_api_curl', array(&$handle) );
+ /**
+ * Fires before the cURL request is executed.
+ *
+ * Cookies are not currently handled by the HTTP API. This action allows
+ * plugins to handle cookies themselves.
+ *
+ * @since 2.8.0
+ *
+ * @param resource &$handle The cURL handle returned by curl_init().
+ * @param array $r The HTTP request arguments.
+ * @param string $url The destination URL.
+ */
+ do_action_ref_array( 'http_api_curl', array( &$handle, $r, $url ) );
// We don't need to return the body, so don't. Just execute request and return.
if ( ! $r['blocking'] ) {
return false;
}
+ /**
+ * Filter whether cURL can be used as a transport for retrieving a URL.
+ *
+ * @since 2.7.0
+ *
+ * @param bool $use_class Whether the class can be used. Default true.
+ * @param array $args An array of request arguments.
+ */
return apply_filters( 'use_curl_transport', true, $args );
}
}
*
* @link http://core.trac.wordpress.org/ticket/4011 Proxy support ticket in WordPress.
* @link http://core.trac.wordpress.org/ticket/14636 Allow wildcard domains in WP_PROXY_BYPASS_HOSTS
- * @since 2.8
+ * @since 2.8.0
*/
class WP_HTTP_Proxy {
/**
* Whether proxy connection should be used.
*
- * @since 2.8
+ * @since 2.8.0
+ *
* @use WP_PROXY_HOST
* @use WP_PROXY_PORT
*
/**
* Whether authentication should be used.
*
- * @since 2.8
+ * @since 2.8.0
+ *
* @use WP_PROXY_USERNAME
* @use WP_PROXY_PASSWORD
*
/**
* Retrieve the host for the proxy server.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
/**
* Retrieve the port for the proxy server.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
/**
* Retrieve the username for proxy authentication.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
/**
* Retrieve the password for proxy authentication.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
/**
* Retrieve authentication string for proxy authentication.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
/**
* Retrieve header string for proxy authentication.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string
*/
$home = parse_url( get_option('siteurl') );
+ /**
+ * Filter whether to preempt sending the request through the proxy server.
+ *
+ * Returning false will bypass the proxy; returning true will send
+ * the request through the proxy. Returning null bypasses the filter.
+ *
+ * @since 3.5.0
+ *
+ * @param null $override Whether to override the request result. Default null.
+ * @param string $uri URL to check.
+ * @param array $check Associative array result of parsing the URI.
+ * @param array $home Associative array result of parsing the site URL.
+ */
$result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home );
if ( ! is_null( $result ) )
return $result;
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 );
}
*
* Includes RFC 1950, RFC 1951, and RFC 1952.
*
- * @since 2.8
+ * @since 2.8.0
* @package WordPress
* @subpackage HTTP
*/
*
* Supports the RFC 1951 standard.
*
- * @since 2.8
+ * @since 2.8.0
*
* @param string $raw String to compress.
* @param int $level Optional, default is 9. Compression level, 9 is highest.
* 1952 standard gzip decode will be attempted. If all fail, then the
* original compressed string will be returned.
*
- * @since 2.8
+ * @since 2.8.0
*
* @param string $compressed String to decompress.
* @param int $length The optional length of the compressed data.
/**
* What encoding types to accept and their priority values.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string Types of encoding to accept.
*/
$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);
/**
* What encoding the content used when it was compressed to send in the headers.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return string Content-Encoding string to send in the header.
*/
/**
* Whether the content be decoded based on the headers.
*
- * @since 2.8
+ * @since 2.8.0
*
* @param array|string $headers All of the available headers.
* @return bool
* ensure that the functions all exist in the PHP version and aren't
* disabled.
*
- * @since 2.8
+ * @since 2.8.0
*
* @return bool
*/