<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27049] trunk/src/wp-includes/class-http.php: Inline documentation for hooks in wp-includes/class-http.php.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27049">27049</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-01-28 08:25:00 +0000 (Tue, 28 Jan 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Inline documentation for hooks in wp-includes/class-http.php.
Props kraftbj for the initial patches. Props kpdesign, DrewAPicture.
Fixes <a href="http://core.trac.wordpress.org/ticket/26049">#26049</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesclasshttpphp">trunk/src/wp-includes/class-http.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesclasshttpphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/class-http.php (27048 => 27049)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/class-http.php 2014-01-28 08:09:13 UTC (rev 27048)
+++ trunk/src/wp-includes/class-http.php 2014-01-28 08:25:00 UTC (rev 27049)
</span><span class="lines">@@ -69,10 +69,48 @@
</span><span class="cx">
</span><span class="cx"> $defaults = array(
</span><span class="cx"> 'method' => 'GET',
</span><del>- 'timeout' => apply_filters( 'http_request_timeout', 5),
- 'redirection' => apply_filters( 'http_request_redirection_count', 5),
- 'httpversion' => apply_filters( 'http_request_version', '1.0'),
</del><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> 'user-agent' => apply_filters( 'http_headers_useragent', 'WordPress/' . $wp_version . '; ' . get_bloginfo( 'url' ) ),
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> 'reject_unsafe_urls' => apply_filters( 'http_request_reject_unsafe_urls', false ),
</span><span class="cx"> 'blocking' => true,
</span><span class="cx"> 'headers' => array(),
</span><span class="lines">@@ -95,13 +133,32 @@
</span><span class="cx"> $defaults['redirection'] = 0;
</span><span class="cx">
</span><span class="cx"> $r = wp_parse_args( $args, $defaults );
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $r = apply_filters( 'http_request_args', $r, $url );
</span><span class="cx">
</span><span class="cx"> // The transports decrement this, store a copy of the original value for loop purposes.
</span><span class="cx"> if ( ! isset( $r['_redirection'] ) )
</span><span class="cx"> $r['_redirection'] = $r['redirection'];
</span><span class="cx">
</span><del>- // Allow plugins to short-circuit the request
</del><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $pre = apply_filters( 'pre_http_request', false, $r, $url );
</span><span class="cx"> if ( false !== $pre )
</span><span class="cx"> return $pre;
</span><span class="lines">@@ -221,6 +278,16 @@
</span><span class="cx"> * @return string|bool Class name for the first transport that claims to support the request. False if no transport claims to support the request.
</span><span class="cx"> */
</span><span class="cx"> public function _get_first_available_transport( $args, $url = null ) {
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $request_order = apply_filters( 'http_api_transports', array( 'curl', 'streams' ), $args, $url );
</span><span class="cx">
</span><span class="cx"> // Loop over each transport on each HTTP request looking for one which will serve this request's needs
</span><span class="lines">@@ -265,11 +332,31 @@
</span><span class="cx">
</span><span class="cx"> $response = $transports[$class]->request( $url, $args );
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> do_action( 'http_api_debug', $response, 'response', $class, $args, $url );
</span><span class="cx">
</span><span class="cx"> if ( is_wp_error( $response ) )
</span><span class="cx"> return $response;
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> return apply_filters( 'http_response', $response, $args, $url );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -281,8 +368,8 @@
</span><span class="cx"> * @access public
</span><span class="cx"> * @since 2.7.0
</span><span class="cx"> *
</span><del>- * @param string $url URI resource.
- * @param str|array $args Optional. Override the defaults.
</del><ins>+ * @param string $url URI resource.
+ * @param string|array $args Optional. Override the defaults.
</ins><span class="cx"> * @return array|object Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
</span><span class="cx"> */
</span><span class="cx"> function post($url, $args = array()) {
</span><span class="lines">@@ -516,8 +603,17 @@
</span><span class="cx"> $home = parse_url( get_option('siteurl') );
</span><span class="cx">
</span><span class="cx"> // Don't block requests back to ourselves by default
</span><del>- if ( $check['host'] == 'localhost' || $check['host'] == $home['host'] )
- return apply_filters('block_local_requests', false);
</del><ins>+ 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 );
+ }
</ins><span class="cx">
</span><span class="cx"> if ( !defined('WP_ACCESSIBLE_HOSTS') )
</span><span class="cx"> return true;
</span><span class="lines">@@ -742,10 +838,25 @@
</span><span class="cx">
</span><span class="cx"> $is_local = isset( $r['local'] ) && $r['local'];
</span><span class="cx"> $ssl_verify = isset( $r['sslverify'] ) && $r['sslverify'];
</span><del>- if ( $is_local )
</del><ins>+ 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.
+ */
</ins><span class="cx"> $ssl_verify = apply_filters( 'https_local_ssl_verify', $ssl_verify );
</span><del>- elseif ( ! $is_local )
</del><ins>+ } 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.
+ */
</ins><span class="cx"> $ssl_verify = apply_filters( 'https_ssl_verify', $ssl_verify );
</span><ins>+ }
</ins><span class="cx">
</span><span class="cx"> $proxy = new WP_HTTP_Proxy();
</span><span class="cx">
</span><span class="lines">@@ -1004,7 +1115,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Whether this class can be used for retrieving an URL.
</del><ins>+ * Whether this class can be used for retrieving a URL.
</ins><span class="cx"> *
</span><span class="cx"> * @static
</span><span class="cx"> * @access public
</span><span class="lines">@@ -1026,6 +1137,14 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> return apply_filters( 'use_streams_transport', true, $args );
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="lines">@@ -1145,10 +1264,13 @@
</span><span class="cx">
</span><span class="cx"> $is_local = isset($r['local']) && $r['local'];
</span><span class="cx"> $ssl_verify = isset($r['sslverify']) && $r['sslverify'];
</span><del>- 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);
</del><ins>+ 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 );
+ }
</ins><span class="cx">
</span><span class="cx"> // CURLOPT_TIMEOUT and CURLOPT_CONNECTTIMEOUT expect integers. Have to use ceil since
</span><span class="cx"> // a value of 0 will allow an unlimited timeout.
</span><span class="lines">@@ -1225,8 +1347,16 @@
</span><span class="cx"> else
</span><span class="cx"> curl_setopt( $handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1 );
</span><span class="cx">
</span><del>- // 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.
</del><ins>+ /**
+ * 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 array $handle cURL options set using curl_setopt().
+ */
</ins><span class="cx"> do_action_ref_array( 'http_api_curl', array(&$handle) );
</span><span class="cx">
</span><span class="cx"> // We don't need to return the body, so don't. Just execute request and return.
</span><span class="lines">@@ -1361,6 +1491,14 @@
</span><span class="cx"> return false;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> return apply_filters( 'use_curl_transport', true, $args );
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="lines">@@ -1529,6 +1667,19 @@
</span><span class="cx">
</span><span class="cx"> $home = parse_url( get_option('siteurl') );
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home );
</span><span class="cx"> if ( ! is_null( $result ) )
</span><span class="cx"> return $result;
</span><span class="lines">@@ -1743,6 +1894,14 @@
</span><span class="cx"> if ( ! isset( $this->name ) || ! isset( $this->value ) )
</span><span class="cx"> return '';
</span><span class="cx">
</span><ins>+ /**
+ * Filter the header-encoded cookie value.
+ *
+ * @since 3.4.0
+ *
+ * @param string $value The cookie value.
+ * @param string $name The cookie name.
+ */
</ins><span class="cx"> return $this->name . '=' . apply_filters( 'wp_http_cookie_value', $this->value, $this->name );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1904,6 +2063,16 @@
</span><span class="cx"> $type[] = 'gzip;q=0.5';
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $type = apply_filters( 'wp_http_accept_encoding', $type, $url, $args );
</span><span class="cx">
</span><span class="cx"> return implode(', ', $type);
</span></span></pre>
</div>
</div>
</body>
</html>