Documentation

Requests
in package

Requests for PHP

Inspired by Requests for Python.

Based on concepts from SimplePie_File, RequestCore and WP_Http.

Table of Contents

Constants

BUFFER_SIZE  = 1160
Default size of buffer size to read streams
DEFAULT_TRANSPORTS  = [\WpOrg\Requests\Transport\Curl::class => \WpOrg\Requests\Transport\Curl::class, \WpOrg\Requests\Transport\Fsockopen::class => \WpOrg\Requests\Transport\Fsockopen::class]
Default supported Transport classes.
DELETE  = 'DELETE'
DELETE method
GET  = 'GET'
GET method
HEAD  = 'HEAD'
HEAD method
OPTION_DEFAULTS  = ['timeout' => 10, 'connect_timeout' => 10, 'useragent' => 'php-requests/' . self::VERSION, 'protocol_version' => 1.1, 'redirected' => 0, 'redirects' => 10, 'follow_redirects' => true, 'blocking' => true, 'type' => self::GET, 'filename' => false, 'auth' => false, 'proxy' => false, 'cookies' => false, 'max_bytes' => false, 'idn' => true, 'hooks' => null, 'transport' => null, 'verify' => null, 'verifyname' => true]
Option defaults.
OPTIONS  = 'OPTIONS'
OPTIONS method
PATCH  = 'PATCH'
PATCH method
POST  = 'POST'
POST method
PUT  = 'PUT'
PUT method
TRACE  = 'TRACE'
TRACE method
VERSION  = '2.0.12'
Current version of Requests

Properties

$transport  : array<string|int, mixed>
Selected transport name
$certificate_path  : string
Default certificate path.
$transports  : array<string|int, mixed>
Registered transport classes
$magic_compression_headers  : array<string|int, mixed>
All (known) valid deflate, gzip header magic markers.

Methods

add_transport()  : mixed
Register a transport
compatible_gzinflate()  : string|bool
Decompression of deflated string while staying compatible with the majority of servers.
decompress()  : string
Decompress an encoded body
delete()  : mixed
Send a DELETE request
flatten()  : array<string|int, mixed>
Convert a key => value array to a 'key: value' array for headers
get()  : mixed
Send a GET request
get_certificate_path()  : string
Get default certificate path.
has_capabilities()  : bool
Checks to see if we have a transport for the capabilities requested.
head()  : mixed
Send a HEAD request
options()  : mixed
Send an OPTIONS request
parse_multiple()  : void
Callback for `transport.internal.parse_response`
patch()  : mixed
Send a PATCH request
post()  : mixed
Send a POST request
put()  : mixed
Send a PUT request
request()  : Response
Main interface for HTTP requests
request_multiple()  : array<string|int, mixed>
Send multiple HTTP requests simultaneously
set_certificate_path()  : mixed
Set default certificate path.
trace()  : mixed
Send a TRACE request
decode_chunked()  : string
Decoded a chunked body as per RFC 2616
get_default_options()  : array<string|int, mixed>
Get the default options
get_transport()  : Transport
Get a working transport.
get_transport_class()  : string
Get the fully qualified class name (FQCN) for a working transport.
parse_response()  : Response
HTTP response parser
set_defaults()  : void
Set the default values
__construct()  : mixed
This is a static class, do not instantiate it

Constants

BUFFER_SIZE

Default size of buffer size to read streams

public int BUFFER_SIZE = 1160

DEFAULT_TRANSPORTS

Default supported Transport classes.

public array<string|int, mixed> DEFAULT_TRANSPORTS = [\WpOrg\Requests\Transport\Curl::class => \WpOrg\Requests\Transport\Curl::class, \WpOrg\Requests\Transport\Fsockopen::class => \WpOrg\Requests\Transport\Fsockopen::class]
Tags
since
2.0.0

DELETE

DELETE method

public string DELETE = 'DELETE'

GET

GET method

public string GET = 'GET'

HEAD

HEAD method

public string HEAD = 'HEAD'

OPTION_DEFAULTS

Option defaults.

public array<string|int, mixed> OPTION_DEFAULTS = ['timeout' => 10, 'connect_timeout' => 10, 'useragent' => 'php-requests/' . self::VERSION, 'protocol_version' => 1.1, 'redirected' => 0, 'redirects' => 10, 'follow_redirects' => true, 'blocking' => true, 'type' => self::GET, 'filename' => false, 'auth' => false, 'proxy' => false, 'cookies' => false, 'max_bytes' => false, 'idn' => true, 'hooks' => null, 'transport' => null, 'verify' => null, 'verifyname' => true]
Tags
see
Requests::get_default_options()
see
Requests::request()

for values returned by this method

since
2.0.0

OPTIONS

OPTIONS method

public string OPTIONS = 'OPTIONS'

POST

POST method

public string POST = 'POST'

PUT

PUT method

public string PUT = 'PUT'

TRACE

TRACE method

public string TRACE = 'TRACE'

VERSION

Current version of Requests

public string VERSION = '2.0.12'

Properties

$transports

Registered transport classes

protected static array<string|int, mixed> $transports = []

$magic_compression_headers

All (known) valid deflate, gzip header magic markers.

private static array<string|int, mixed> $magic_compression_headers = [ "\x1f\x8b" => true, // Gzip marker. "x\x01" => true, // Zlib marker - level 1. "x^" => true, // Zlib marker - level 2 to 5. "x\x9c" => true, // Zlib marker - level 6. "x\xda" => true, ]

These markers relate to different compression levels.

Tags
link

Marker source.
since
2.0.0

Methods

add_transport()

Register a transport

public static add_transport(string $transport) : mixed
Parameters
$transport : string

Transport class to add, must support the \WpOrg\Requests\Transport interface

compatible_gzinflate()

Decompression of deflated string while staying compatible with the majority of servers.

public static compatible_gzinflate(string $gz_data) : string|bool

Certain Servers will return deflated data with headers which PHP's gzinflate() function cannot handle out of the box. The following function has been created from various snippets on the gzinflate() PHP documentation.

Warning: Magic numbers within. Due to the potential different formats that the compressed data may be returned in, some "magic offsets" are needed to ensure proper decompression takes place. For a simple progmatic way to determine the magic offset in use, see: https://core.trac.wordpress.org/ticket/18273

Parameters
$gz_data : string

String to decompress.

Tags
since
1.6.0
link
https://core.trac.wordpress.org/ticket/18273
link
https://www.php.net/gzinflate#70875
link
https://www.php.net/gzinflate#77336
throws
InvalidArgument

When the passed argument is not a string.

Return values
string|bool —

False on failure.

decompress()

Decompress an encoded body

public static decompress(string $data) : string

Implements gzip, compress and deflate. Guesses which it is by attempting to decode.

Parameters
$data : string

Compressed data in one of the above formats

Tags
throws
InvalidArgument

When the passed argument is not a string.

Return values
string —

Decompressed string

delete()

Send a DELETE request

public static delete(mixed $url[, mixed $headers = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$options : mixed = []

flatten()

Convert a key => value array to a 'key: value' array for headers

public static flatten(iterable<string|int, mixed> $dictionary) : array<string|int, mixed>
Parameters
$dictionary : iterable<string|int, mixed>

Dictionary of header values

Tags
throws
InvalidArgument

When the passed argument is not iterable.

Return values
array<string|int, mixed> —

List of headers

get()

Send a GET request

public static get(mixed $url[, mixed $headers = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$options : mixed = []

get_certificate_path()

Get default certificate path.

public static get_certificate_path() : string
Return values
string —

Default certificate path.

has_capabilities()

Checks to see if we have a transport for the capabilities requested.

public static has_capabilities([array<string, bool> $capabilities = [] ]) : bool

Supported capabilities can be found in the Capability interface as constants.

Example usage: Requests::has_capabilities([Capability::SSL => true]).

Parameters
$capabilities : array<string, bool> = []

Optional. Associative array of capabilities to test against, i.e. ['<capability>' => true].

Return values
bool —

Whether the transport has the requested capabilities.

head()

Send a HEAD request

public static head(mixed $url[, mixed $headers = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$options : mixed = []

options()

Send an OPTIONS request

public static options(mixed $url[, mixed $headers = [] ][, mixed $data = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$data : mixed = []
$options : mixed = []

parse_multiple()

Callback for `transport.internal.parse_response`

public static parse_multiple(string &$response, array<string|int, mixed> $request) : void

Internal use only. Converts a raw HTTP response to a \WpOrg\Requests\Response while still executing a multiple request.

$response is either set to a \WpOrg\Requests\Response instance, or a \WpOrg\Requests\Exception object

Parameters
$response : string

Full response text including headers and body (will be overwritten with Response instance)

$request : array<string|int, mixed>

Request data as passed into Requests::request_multiple()

patch()

Send a PATCH request

public static patch(mixed $url, mixed $headers[, mixed $data = [] ][, mixed $options = [] ]) : mixed

Note: Unlike Requests::post() and Requests::put(), $headers is required, as the specification recommends that should send an ETag

Parameters
$url : mixed
$headers : mixed
$data : mixed = []
$options : mixed = []
Tags
link
https://tools.ietf.org/html/rfc5789

post()

Send a POST request

public static post(mixed $url[, mixed $headers = [] ][, mixed $data = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$data : mixed = []
$options : mixed = []

put()

Send a PUT request

public static put(mixed $url[, mixed $headers = [] ][, mixed $data = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$data : mixed = []
$options : mixed = []

request()

Main interface for HTTP requests

public static request(string|Stringable $url[, array<string|int, mixed> $headers = [] ][, array<string|int, mixed>|null $data = [] ][, string $type = self::GET ][, array<string|int, mixed> $options = [] ]) : Response

This method initiates a request and sends it via a transport before parsing.

The $options parameter takes an associative array with the following options:

  • timeout: How long should we wait for a response? Note: for cURL, a minimum of 1 second applies, as DNS resolution operates at second-resolution only. (float, seconds with a millisecond precision, default: 10, example: 0.01)
  • connect_timeout: How long should we wait while trying to connect? (float, seconds with a millisecond precision, default: 10, example: 0.01)
  • useragent: Useragent to send to the server (string, default: php-requests/$version)
  • follow_redirects: Should we follow 3xx redirects? (boolean, default: true)
  • redirects: How many times should we redirect before erroring? (integer, default: 10)
  • blocking: Should we block processing on this request? (boolean, default: true)
  • filename: File to stream the body to instead. (string|boolean, default: false)
  • auth: Authentication handler or array of user/password details to use for Basic authentication (\WpOrg\Requests\Auth|array|boolean, default: false)
  • proxy: Proxy details to use for proxy by-passing and authentication (\WpOrg\Requests\Proxy|array|string|boolean, default: false)
  • max_bytes: Limit for the response body size. (integer|boolean, default: false)
  • idn: Enable IDN parsing (boolean, default: true)
  • transport: Custom transport. Either a class name, or a transport object. Defaults to the first working transport from Requests::getTransport() (string|\WpOrg\Requests\Transport, default: Requests::getTransport())
  • hooks: Hooks handler. (\WpOrg\Requests\HookManager, default: new WpOrg\Requests\Hooks())
  • verify: Should we verify SSL certificates? Allows passing in a custom certificate file as a string. (Using true uses the system-wide root certificate store instead, but this may have different behaviour across transports.) (string|boolean, default: certificates/cacert.pem)
  • verifyname: Should we verify the common name in the SSL certificate? (boolean, default: true)
  • data_format: How should we send the $data parameter? (string, one of 'query' or 'body', default: 'query' for HEAD/GET/DELETE, 'body' for POST/PUT/OPTIONS/PATCH)
Parameters
$url : string|Stringable

URL to request

$headers : array<string|int, mixed> = []

Extra headers to send with the request

$data : array<string|int, mixed>|null = []

Data to send either as a query string for GET/HEAD requests, or in the body for POST requests

$type : string = self::GET

HTTP request type (use Requests constants)

$options : array<string|int, mixed> = []

Options for the request (see description for more information)

Tags
throws
InvalidArgument

When the passed $url argument is not a string or Stringable.

throws
InvalidArgument

When the passed $type argument is not a string.

throws
InvalidArgument

When the passed $options argument is not an array.

throws
Exception

On invalid URLs (nonhttp)

Return values
Response

request_multiple()

Send multiple HTTP requests simultaneously

public static request_multiple(array<string|int, mixed> $requests[, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

The $requests parameter takes an associative or indexed array of request fields. The key of each request can be used to match up the request with the returned data, or with the request passed into your multiple.request.complete callback.

The request fields value is an associative array with the following keys:

  • url: Request URL Same as the $url parameter to Requests::request() (string, required)
  • headers: Associative array of header fields. Same as the $headers parameter to Requests::request() (array, default: array())
  • data: Associative array of data fields or a string. Same as the $data parameter to Requests::request() (array|string, default: array())
  • type: HTTP request type (use \WpOrg\Requests\Requests constants). Same as the $type parameter to Requests::request() (string, default: \WpOrg\Requests\Requests::GET)
  • cookies: Associative array of cookie name to value, or cookie jar. (array|\WpOrg\Requests\Cookie\Jar)

If the $options parameter is specified, individual requests will inherit options from it. This can be used to use a single hooking system, or set all the types to \WpOrg\Requests\Requests::POST, for example.

In addition, the $options parameter takes the following global options:

  • complete: A callback for when a request is complete. Takes two parameters, a \WpOrg\Requests\Response/\WpOrg\Requests\Exception reference, and the ID from the request array (Note: this can also be overridden on a per-request basis, although that's a little silly) (callback)
Parameters
$requests : array<string|int, mixed>

Requests data (see description for more information)

$options : array<string|int, mixed> = []

Global and default options (see Requests::request())

Tags
throws
InvalidArgument

When the passed $requests argument is not an array or iterable object with array access.

throws
InvalidArgument

When the passed $options argument is not an array.

Return values
array<string|int, mixed> —

Responses (either \WpOrg\Requests\Response or a \WpOrg\Requests\Exception object)

set_certificate_path()

Set default certificate path.

public static set_certificate_path(string|Stringable|bool $path) : mixed
Parameters
$path : string|Stringable|bool

Certificate path, pointing to a PEM file.

Tags
throws
InvalidArgument

When the passed $url argument is not a string, Stringable or boolean.

trace()

Send a TRACE request

public static trace(mixed $url[, mixed $headers = [] ][, mixed $options = [] ]) : mixed
Parameters
$url : mixed
$headers : mixed = []
$options : mixed = []

get_default_options()

Get the default options

protected static get_default_options([bool $multirequest = false ]) : array<string|int, mixed>
Parameters
$multirequest : bool = false

Is this a multirequest?

Tags
see
Requests::request()

for values returned by this method

Return values
array<string|int, mixed> —

Default option values

get_transport()

Get a working transport.

protected static get_transport([array<string, bool> $capabilities = [] ]) : Transport
Parameters
$capabilities : array<string, bool> = []

Optional. Associative array of capabilities to test against, i.e. ['<capability>' => true].

Tags
throws
Exception

If no valid transport is found (notransport).

Return values
Transport

get_transport_class()

Get the fully qualified class name (FQCN) for a working transport.

protected static get_transport_class([array<string, bool> $capabilities = [] ]) : string
Parameters
$capabilities : array<string, bool> = []

Optional. Associative array of capabilities to test against, i.e. ['<capability>' => true].

Return values
string —

FQCN of the transport to use, or an empty string if no transport was found which provided the requested capabilities.

parse_response()

HTTP response parser

protected static parse_response(string $headers, string $url, array<string|int, mixed> $req_headers, array<string|int, mixed> $req_data, array<string|int, mixed> $options) : Response
Parameters
$headers : string

Full response text including headers and body

$url : string

Original request URL

$req_headers : array<string|int, mixed>

Original $headers array passed to , in case we need to follow redirects

$req_data : array<string|int, mixed>

Original $data array passed to , in case we need to follow redirects

$options : array<string|int, mixed>

Original $options array passed to , in case we need to follow redirects

Tags
throws
Exception

On missing head/body separator (requests.no_crlf_separator)

throws
Exception

On missing head/body separator (noversion)

throws
Exception

On missing head/body separator (toomanyredirects)

Return values
Response

set_defaults()

Set the default values

protected static set_defaults(string &$url, array<string|int, mixed> &$headers, array<string|int, mixed>|null &$data, string &$type, array<string|int, mixed> &$options) : void

The $options parameter is updated with the results.

Parameters
$url : string

URL to request

$headers : array<string|int, mixed>

Extra headers to send with the request

$data : array<string|int, mixed>|null

Data to send either as a query string for GET/HEAD requests, or in the body for POST requests

$type : string

HTTP request type

$options : array<string|int, mixed>

Options for the request

Tags
throws
Exception

When the $url is not an http(s) URL.

__construct()

This is a static class, do not instantiate it

private __construct() : mixed
Tags
codeCoverageIgnore 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results