WordPress HTTP Class for managing HTTP Transports and making HTTP requests.
This class is called for the functionality of making HTTP requests and should replace Snoopy functionality, eventually. There is no available functionality to add HTTP transport implementations, since most of the HTTP transports are added and available for use.
The exception is that cURL is not available as a transport and lacking an implementation. It will be added later and should be a patch on the WordPress Trac.
There are no properties, because none are needed and for performance reasons. Some of the functions are static and while they do have some overhead over functions in PHP4, the purpose is maintainability. When PHP5 is finally the requirement, it will be easy to add the static keyword to the code. It is not as easy to convert a function to a method after enough code uses the old way.
Debugging includes several actions, which pass different variables for debugging the HTTP API.
http_transport_get_debug - gives working, nonblocking, and blocking transports.
http_transport_post_debug - gives working, nonblocking, and blocking transports.
| package | WordPress |
|---|---|
| subpackage | HTTP |
| since | 2.7.0 |
WP_Http() : \WP_Http
| since | 2.7.0 |
|---|
\WP_Http__construct() : \WP_Http
PHP4 does not have the 'self' keyword and since WordPress supports PHP4, the class needs to be used for the static call.
The transport are setup to save time. This should only be called once, so the overhead should be fine.
| since | 2.7.0 |
|---|
\WP_Http_getTransport(array $args = array()) : object | null
Tests all of the objects and returns the object that passes. Also caches that object to be used later.
The order for the GET/HEAD requests are HTTP Extension, FSockopen Streams, Fopen, and finally cURL. Whilst Fsockopen has the highest overhead, Its used 2nd due to high compatibility with most hosts, The HTTP Extension is tested first due to hosts which have it enabled, are likely to work correctly with it.
There are currently issues with "localhost" not resolving correctly with DNS. This may cause an error "failed to open stream: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond."
| since | 2.7.0 |
|---|---|
| access | private |
arrayRequest args, default us an empty array
objectnullNull if no transports are available, HTTP transport object._postTransport(array $args = array()) : object | null
Tests all of the objects and returns the object that passes. Also caches that object to be used later. This is for posting content to a URL and is used when there is a body. The plain Fopen Transport can not be used to send content, but the streams transport can. This is a limitation that is addressed here, by just not including that transport.
| since | 2.7.0 |
|---|---|
| access | private |
arrayRequest args, default us an empty array
objectnullNull if no transports are available, HTTP transport object.block_request(string $uri) : boolean
Those who are behind a proxy and want to prevent access to certain hosts may do so. This will prevent plugins from working and core functionality, if you don't include api.wordpress.org.
You block external URL requests by defining WP_HTTP_BLOCK_EXTERNAL in your wp-config.php file and this will only allow localhost and your blog to make requests. The constant WP_ACCESSIBLE_HOSTS will allow additional hosts to go through for requests. The format of the WP_ACCESSIBLE_HOSTS constant is a comma separated list of hostnames to allow.
| since | 2.8.0 |
|---|---|
| link | Allow preventing external requests. |
stringURI of url.
booleanTrue to block, false to allow.buildCookieHeader(array $r)
If it's found, then it's assumed to contain WP_Http_Cookie objects, which are each parsed into strings and added to the Cookie: header (within the arguments array). Edits the array by reference.
| access | public |
|---|---|
| version | 2.8.0 |
| static |
arrayFull array of args passed into ::request()
chunkTransferDecode(string $body) : string
Based off the HTTP http_encoding_dechunk function. Does not support UTF-8. Does not support returning footer headers. Shouldn't be too difficult to support it though.
| todo | Add support for footer chunked headers. |
|---|---|
| access | public |
| since | 2.7.0 |
| static |
stringBody content
stringChunked decoded body on success or raw body on failure.get(string $url, \str|array $args = array()) : boolean
Used for sending data that is expected to be in the body.
| access | public |
|---|---|
| since | 2.7.0 |
stringURI resource.
\strarrayOptional. Override the defaults.
booleanhead(string $url, \str|array $args = array()) : boolean
Used for sending data that is expected to be in the body.
| access | public |
|---|---|
| since | 2.7.0 |
stringURI resource.
\strarrayOptional. Override the defaults.
booleanpost(string $url, \str|array $args = array()) : boolean
Used for sending data that is expected to be in the body.
| access | public |
|---|---|
| since | 2.7.0 |
stringURI resource.
\strarrayOptional. Override the defaults.
booleanprocessHeaders(string|array $headers) : array
If an array is given then it is assumed to be raw header data with numeric keys with the headers as the values. No headers must be passed that were already processed.
| access | public |
|---|---|
| static | |
| since | 2.7.0 |
stringarray
arrayProcessed string headers. If duplicate headers are encountered,
Then a numbered array is returned as the value of that header-key.processResponse(string $strResponse) : array
| access | public |
|---|---|
| static | |
| since | 2.7.0 |
stringThe full response string
arrayArray with 'headers' and 'body' keys.request(string $url, \str|array $args = array()) : array
The body and headers are part of the arguments. The 'body' argument is for the body and will accept either a string or an array. The 'headers' argument should be an array, but a string is acceptable. If the 'body' argument is an array, then it will automatically be escaped using http_build_query().
The only URI that are supported in the HTTP Transport implementation are the HTTP and HTTPS protocols. HTTP and HTTPS are assumed so the server might not know how to handle the send headers. Other protocols are unsupported and most likely will fail.
The defaults are 'method', 'timeout', 'redirection', 'httpversion', 'blocking' and 'user-agent'.
Accepted 'method' values are 'GET', 'POST', and 'HEAD', some transports technically allow others, but should not be assumed. The 'timeout' is used to sent how long the connection should stay open before failing when no response. 'redirection' is used to track how many redirects were taken and used to sent the amount for other transports, but not all transports accept setting that value.
The 'httpversion' option is used to sent the HTTP version and accepted values are '1.0', and '1.1' and should be a string. Version 1.1 is not supported, because of chunk response. The 'user-agent' option is the user-agent and is used to replace the default user-agent, which is 'WordPress/WP_Version', where WP_Version is the value from $wp_version.
'blocking' is the default, which is used to tell the transport, whether it should halt PHP while it performs the request or continue regardless. Actually, that isn't entirely correct. Blocking mode really just means whether the fread should just pull what it can whenever it gets bytes or if it should wait until it has enough in the buffer to read or finishes reading the entire content. It doesn't actually always mean that PHP will continue going after making the request.
| access | public |
|---|---|
| since | 2.7.0 |
stringURI resource.
\strarrayOptional. Override the defaults.
arraycontaining 'headers', 'body', 'response', 'cookies'