[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-forums/bbpress/bb-includes/backpress/ -> class.wp-http.php (summary)

[Source view] [Print] [Project Stats]

Simple and uniform HTTP request API. Will eventually replace and standardize the WordPress HTTP requests made.

Author: Jacob Santos <wordpress@santosj.name>
File Size: 2052 lines (66 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 9 classes

WP_Http:: (13 methods):
  WP_Http()
  __construct()
  _getTransport()
  _postTransport()
  request()
  post()
  get()
  head()
  processResponse()
  processHeaders()
  buildCookieHeader()
  chunkTransferDecode()
  block_request()

WP_Http_Fsockopen:: (2 methods):
  request()
  test()

WP_Http_Fopen:: (2 methods):
  request()
  test()

WP_Http_Streams:: (2 methods):
  request()
  test()

WP_Http_ExtHTTP:: (2 methods):
  request()
  test()

WP_Http_Curl:: (2 methods):
  request()
  test()

WP_HTTP_Proxy:: (9 methods):
  is_enabled()
  use_authentication()
  host()
  port()
  username()
  password()
  authentication()
  authentication_header()
  send_through_proxy()

WP_Http_Cookie:: (5 methods):
  WP_Http_Cookie()
  __construct()
  test()
  getHeaderValue()
  getFullHeader()

WP_Http_Encoding:: (16 methods):
  compress()
  decompress()
  accept_encoding()
  content_encoding()
  should_decode()
  is_available()
  _wp_http_get_object()
  wp_remote_request()
  wp_remote_get()
  wp_remote_post()
  wp_remote_head()
  wp_remote_retrieve_headers()
  wp_remote_retrieve_header()
  wp_remote_retrieve_response_code()
  wp_remote_retrieve_response_message()
  wp_remote_retrieve_body()


Class: WP_Http  - X-Ref

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.

<strong>http_transport_get_debug</strong> - gives working, nonblocking, and blocking transports.

<strong>http_transport_post_debug</strong> - gives working, nonblocking, and blocking transports.

WP_Http()   X-Ref
PHP4 style Constructor - Calls PHP5 Style Constructor

since: 2.7.0
return: WP_Http

__construct()   X-Ref
PHP5 style Constructor - Setup available transport if not available.

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
return: WP_Http

_getTransport( $args = array()   X-Ref
Tests the WordPress HTTP objects for an object to use and returns it.

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."

param: array $args Request args, default us an empty array
since: 2.7.0
return: object|null Null if no transports are available, HTTP transport object.

_postTransport( $args = array()   X-Ref
Tests the WordPress HTTP objects for an object to use and returns it.

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.

param: array $args Request args, default us an empty array
since: 2.7.0
return: object|null Null if no transports are available, HTTP transport object.

request( $url, $args = array()   X-Ref
Send a HTTP request to a URI.

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.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: array containing 'headers', 'body', 'response', 'cookies'

post($url, $args = array()   X-Ref
Uses the POST HTTP method.

Used for sending data that is expected to be in the body.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: boolean

get($url, $args = array()   X-Ref
Uses the GET HTTP method.

Used for sending data that is expected to be in the body.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: boolean

head($url, $args = array()   X-Ref
Uses the HEAD HTTP method.

Used for sending data that is expected to be in the body.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: boolean

processResponse($strResponse)   X-Ref
Parses the responses and splits the parts into headers and body.

param: string $strResponse The full response string
since: 2.7.0
return: array Array with 'headers' and 'body' keys.

processHeaders($headers)   X-Ref
Transform header string into an 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.

param: string|array $headers
since: 2.7.0
return: array Processed string headers. If duplicate headers are encountered,

buildCookieHeader( &$r )   X-Ref
Takes the arguments for a ::request() and checks for the cookie array.

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.

param: array $r Full array of args passed into ::request()

chunkTransferDecode($body)   X-Ref
Decodes chunk transfer-encoding, based off the HTTP 1.1 specification.

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.

param: string $body Body content
since: 2.7.0
return: string Chunked decoded body on success or raw body on failure.

block_request($uri)   X-Ref
Block requests through the proxy.

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.

param: string $uri URI of url.
since: 2.8.0
return: bool True to block, false to allow.

Class: WP_Http_Fsockopen  - X-Ref

HTTP request method uses fsockopen function to retrieve the url.

This would be the preferred method, but the fsockopen implementation has the most overhead of all
the HTTP transport implementations.

request($url, $args = array()   X-Ref
Send a HTTP request to a URI using fsockopen().

Does not support non-blocking mode.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7
return: array 'headers', 'body', 'cookies' and 'response' keys.

test( $args = array()   X-Ref
Whether this class can be used for retrieving an URL.

since: 2.7.0
return: boolean False means this class can not be used, true means it can.

Class: WP_Http_Fopen  - X-Ref

HTTP request method uses fopen function to retrieve the url.

Requires PHP version greater than 4.3.0 for stream support. Does not allow for $context support,
but should still be okay, to write the headers, before getting the response. Also requires that
'allow_url_fopen' to be enabled.

request($url, $args = array()   X-Ref
Send a HTTP request to a URI using fopen().

This transport does not support sending of headers and body, therefore should not be used in
the instances, where there is a body and headers.

Notes: Does not support non-blocking mode. Ignores 'redirection' option.

param: string $url URI resource.
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: array 'headers', 'body', 'cookies' and 'response' keys.

test($args = array()   X-Ref
Whether this class can be used for retrieving an URL.

since: 2.7.0
return: boolean False means this class can not be used, true means it can.

Class: WP_Http_Streams  - X-Ref

HTTP request method uses Streams to retrieve the url.

Requires PHP 5.0+ and uses fopen with stream context. Requires that 'allow_url_fopen' PHP setting
to be enabled.

Second preferred method for getting the URL, for PHP 5.

request($url, $args = array()   X-Ref
Send a HTTP request to a URI using streams with fopen().

param: string $url
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: array 'headers', 'body', 'cookies' and 'response' keys.

test($args = array()   X-Ref
Whether this class can be used for retrieving an URL.

since: 2.7.0
return: boolean False means this class can not be used, true means it can.

Class: WP_Http_ExtHTTP  - X-Ref

HTTP request method uses HTTP extension to retrieve the url.

Requires the HTTP extension to be installed. This would be the preferred transport since it can
handle a lot of the problems that forces the others to use the HTTP version 1.0. Even if PHP 5.2+
is being used, it doesn't mean that the HTTP extension will be enabled.

request($url, $args = array()   X-Ref
Send a HTTP request to a URI using HTTP extension.

Does not support non-blocking.

param: string $url
param: str|array $args Optional. Override the defaults.
since: 2.7
return: array 'headers', 'body', 'cookies' and 'response' keys.

test($args = array()   X-Ref
Whether this class can be used for retrieving an URL.

since: 2.7.0
return: boolean False means this class can not be used, true means it can.

Class: WP_Http_Curl  - X-Ref

HTTP request method uses Curl extension to retrieve the url.

Requires the Curl extension to be installed.

request($url, $args = array()   X-Ref
Send a HTTP request to a URI using cURL extension.

param: string $url
param: str|array $args Optional. Override the defaults.
since: 2.7.0
return: array 'headers', 'body', 'cookies' and 'response' keys.

test($args = array()   X-Ref
Whether this class can be used for retrieving an URL.

since: 2.7.0
return: boolean False means this class can not be used, true means it can.

Class: WP_HTTP_Proxy  - X-Ref

Adds Proxy support to the WordPress HTTP API.

There are caveats to proxy support. It requires that defines be made in the wp-config.php file to
enable proxy support. There are also a few filters that plugins can hook into for some of the
constants.

The constants are as follows:
<ol>
<li>WP_PROXY_HOST - Enable proxy support and host for connecting.</li>
<li>WP_PROXY_PORT - Proxy port for connection. No default, must be defined.</li>
<li>WP_PROXY_USERNAME - Proxy username, if it requires authentication.</li>
<li>WP_PROXY_PASSWORD - Proxy password, if it requires authentication.</li>
<li>WP_PROXY_BYPASS_HOSTS - Will prevent the hosts in this list from going through the proxy.
You do not need to have localhost and the blog host in this list, because they will not be passed
through the proxy. The list should be presented in a comma separated list</li>
</ol>

An example can be as seen below.
<code>
define('WP_PROXY_HOST', '192.168.84.101');
define('WP_PROXY_PORT', '8080');
define('WP_PROXY_BYPASS_HOSTS', 'localhost, www.example.com');
</code>

is_enabled()   X-Ref
Whether proxy connection should be used.

since: 2.8
return: bool

use_authentication()   X-Ref
Whether authentication should be used.

since: 2.8
return: bool

host()   X-Ref
Retrieve the host for the proxy server.

since: 2.8
return: string

port()   X-Ref
Retrieve the port for the proxy server.

since: 2.8
return: string

username()   X-Ref
Retrieve the username for proxy authentication.

since: 2.8
return: string

password()   X-Ref
Retrieve the password for proxy authentication.

since: 2.8
return: string

authentication()   X-Ref
Retrieve authentication string for proxy authentication.

since: 2.8
return: string

authentication_header()   X-Ref
Retrieve header string for proxy authentication.

since: 2.8
return: string

send_through_proxy( $uri )   X-Ref
Whether URL should be sent through the proxy server.

We want to keep localhost and the blog URL from being sent through the proxy server, because
some proxies can not handle this. We also have the constant available for defining other
hosts that won't be sent through the proxy.

param: string $uri URI to check.
since: unknown
return: bool True, to send through the proxy and false if, the proxy should not be used.

Class: WP_Http_Cookie  - X-Ref

Internal representation of a single cookie.

Returned cookies are represented using this class, and when cookies are set, if they are not
already a WP_Http_Cookie() object, then they are turned into one.

WP_Http_Cookie( $data )   X-Ref
PHP4 style Constructor - Calls PHP5 Style Constructor.

param: string|array $data Raw cookie data.
since: 2.8.0

__construct( $data )   X-Ref
Sets up this cookie object.

The parameter $data should be either an associative array containing the indices names below
or a header string detailing it.

If it's an array, it should include the following elements:
<ol>
<li>Name</li>
<li>Value - should NOT be urlencoded already.</li>
<li>Expires - (optional) String or int (UNIX timestamp).</li>
<li>Path (optional)</li>
<li>Domain (optional)</li>
</ol>

param: string|array $data Raw cookie data.
since: 2.8.0

test( $url )   X-Ref
Confirms that it's OK to send this cookie to the URL checked against.

Decision is based on RFC 2109/2965, so look there for details on validity.

param: string $url URL you intend to send this cookie to
since: 2.8.0
return: boolean TRUE if allowed, FALSE otherwise.

getHeaderValue()   X-Ref
Convert cookie name and value back to header string.

since: 2.8.0
return: string Header encoded cookie name and value.

getFullHeader()   X-Ref
Retrieve cookie header for usage in the rest of the WordPress HTTP API.

since: 2.8.0
return: string

Class: WP_Http_Encoding  - X-Ref

Implementation for deflate and gzip transfer encodings.

Includes RFC 1950, RFC 1951, and RFC 1952.

compress( $raw, $level = 9, $supports = null )   X-Ref
Compress raw string using the deflate format.

Supports the RFC 1951 standard.

param: string $raw String to compress.
param: int $level Optional, default is 9. Compression level, 9 is highest.
param: string $supports Optional, not used. When implemented it will choose the right compression based on what the server supports.
since: 2.8
return: string|bool False on failure.

decompress( $compressed, $length = null )   X-Ref
Decompression of deflated string.

Will attempt to decompress using the RFC 1950 standard, and if that fails
then the RFC 1951 standard deflate will be attempted. Finally, the RFC
1952 standard gzip decode will be attempted. If all fail, then the
original compressed string will be returned.

param: string $compressed String to decompress.
param: int $length The optional length of the compressed data.
since: 2.8
return: string|bool False on failure.

accept_encoding()   X-Ref
What encoding types to accept and their priority values.

since: 2.8
return: string Types of encoding to accept.

content_encoding()   X-Ref
What enconding the content used when it was compressed to send in the headers.

since: 2.8
return: string Content-Encoding string to send in the header.

should_decode($headers)   X-Ref
Whether the content be decoded based on the headers.

param: array|string $headers All of the available headers.
since: 2.8
return: bool

is_available()   X-Ref
Whether decompression and compression are supported by the PHP version.

Each function is tested instead of checking for the zlib extension, to
ensure that the functions all exist in the PHP version and aren't
disabled.

since: 2.8
return: bool

_wp_http_get_object()   X-Ref
Returns the initialized WP_Http Object

since: 2.7.0
return: WP_Http HTTP Transport object.

wp_remote_request($url, $args = array()   X-Ref
Retrieve the raw response from the HTTP request.

The array structure is a little complex.

<code>
$res = array( 'headers' => array(), 'response' => array('code' => int, 'message' => string) );
</code>

All of the headers in $res['headers'] are with the name as the key and the
value as the value. So to get the User-Agent, you would do the following.

<code>
$user_agent = $res['headers']['user-agent'];
</code>

The body is the raw response content and can be retrieved from $res['body'].

This function is called first to make the request and there are other API
functions to abstract out the above convoluted setup.

param: string $url Site URL to retrieve.
param: array $args Optional. Override the defaults.
since: 2.7.0
return: WP_Error|array The response or WP_Error on failure.

wp_remote_get($url, $args = array()   X-Ref
Retrieve the raw response from the HTTP request using the GET method.

param: string $url Site URL to retrieve.
param: array $args Optional. Override the defaults.
since: 2.7.0
return: WP_Error|array The response or WP_Error on failure.

wp_remote_post($url, $args = array()   X-Ref
Retrieve the raw response from the HTTP request using the POST method.

param: string $url Site URL to retrieve.
param: array $args Optional. Override the defaults.
since: 2.7.0
return: WP_Error|array The response or WP_Error on failure.

wp_remote_head($url, $args = array()   X-Ref
Retrieve the raw response from the HTTP request using the HEAD method.

param: string $url Site URL to retrieve.
param: array $args Optional. Override the defaults.
since: 2.7.0
return: WP_Error|array The response or WP_Error on failure.

wp_remote_retrieve_headers(&$response)   X-Ref
Retrieve only the headers from the raw response.

param: array $response HTTP response.
since: 2.7.0
return: array The headers of the response. Empty array if incorrect parameter given.

wp_remote_retrieve_header(&$response, $header)   X-Ref
Retrieve a single header by name from the raw response.

param: array $response
param: string $header Header name to retrieve value from.
since: 2.7.0
return: string The header value. Empty string on if incorrect parameter given, or if the header doesnt exist.

wp_remote_retrieve_response_code(&$response)   X-Ref
Retrieve only the response code from the raw response.

Will return an empty array if incorrect parameter value is given.

param: array $response HTTP response.
since: 2.7.0
return: string the response code. Empty string on incorrect parameter given.

wp_remote_retrieve_response_message(&$response)   X-Ref
Retrieve only the response message from the raw response.

Will return an empty array if incorrect parameter value is given.

param: array $response HTTP response.
since: 2.7.0
return: string The response message. Empty string on incorrect parameter given.

wp_remote_retrieve_body(&$response)   X-Ref
Retrieve only the body from the raw response.

param: array $response HTTP response.
since: 2.7.0
return: string The body of the response. Empty string if no body or incorrect parameter given.


Generated: Sun Dec 22 01:00:54 2024 Cross-referenced by PHPXref 0.7.1