API Documentation
Back to top  

Requests for PHP

Inspired by Requests for Python.

Based on concepts from SimplePie_File, RequestCore and WP_Http.

package Requests

 Methods

Register a transport

add_transport(string $transport) 
Static

Parameters

$transport

string

Transport class to add, must support the Requests_Transport interface

Autoloader for Requests

autoloader(string $class) 
Static

Register this with \register_autoloader() if you'd like to avoid having to create your own.

(You can also use spl_autoload_register directly if you'd prefer.)

codeCoverageIgnore

Parameters

$class

string

Class name to load

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

compatible_gzinflate(string $gzData) : string | boolean
Static

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

since 2.8.1
link https://core.trac.wordpress.org/ticket/18273
link https://secure.php.net/manual/en/function.gzinflate.php#70875
link https://secure.php.net/manual/en/function.gzinflate.php#77336

Parameters

$gzData

string

String to decompress.

Returns

stringbooleanFalse on failure.

Decompress an encoded body

decompress(string $data) : string
Static

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

Parameters

$data

string

Compressed data in one of the above formats

Returns

stringDecompressed string

Send a DELETE request

delete($url, $headers = array(), $options = array()) 
Static

Parameters

$url

$headers

$options

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

flatten(array $array) : array
Static

Parameters

$array

array

Dictionary of header values

Returns

arrayList of headers

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

flattern(array $array) : array
Static
codeCoverageIgnore
deprecated Misspelling of {@see Requests::flatten}

Parameters

$array

array

Dictionary of header values

Returns

arrayList of headers

Send a GET request

get($url, $headers = array(), $options = array()) 
Static

Parameters

$url

$headers

$options

Get default certificate path.

get_certificate_path() : string
Static

Returns

stringDefault certificate path.

Send a HEAD request

head($url, $headers = array(), $options = array()) 
Static

Parameters

$url

$headers

$options

match_domain() 

match_domain($host, $reference) 
Static

Parameters

$host

$reference

Send an OPTIONS request

options($url, $headers = array(), $data = array(), $options = array()) 
Static

Parameters

$url

$headers

$data

$options

Callback for `transport.internal.parse_response`

parse_multiple(string $response, array $request) : null
Static

Internal use only. Converts a raw HTTP response to a Requests_Response while still executing a multiple request.

Parameters

$response

string

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

$request

array

Request data as passed into {@see Requests::request_multiple()}

Returns

null`$response` is either set to a Requests_Response instance, or a Requests_Exception object

Send a PATCH request

patch($url, $headers, $data = array(), $options = array()) 
Static

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

link https://tools.ietf.org/html/rfc5789

Parameters

$url

$headers

$data

$options

Send a POST request

post($url, $headers = array(), $data = array(), $options = array()) 
Static

Parameters

$url

$headers

$data

$options

Send a PUT request

put($url, $headers = array(), $data = array(), $options = array()) 
Static

Parameters

$url

$headers

$data

$options

Register the built-in autoloader

register_autoloader() 
Static
codeCoverageIgnore

Main interface for HTTP requests

request(string $url, array $headers = array(), array|null $data = array(), string $type = self::GET, array $options = array()) : \Requests_Response
Static

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 (Requests_Auth|array|boolean, default: false)
  • proxy: Proxy details to use for proxy by-passing and authentication (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 \getTransport() (string|Requests_Transport, default: \getTransport())
  • hooks: Hooks handler. (Requests_Hooker, default: new 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: library/Requests/Transport/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

URL to request

$headers

array

Extra headers to send with the request

$data

arraynull

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

$type

string

HTTP request type (use Requests constants)

$options

array

Options for the request (see description for more information)

Exceptions

\Requests_Exception On invalid URLs (`nonhttp`)

Returns

\Requests_Response

Send multiple HTTP requests simultaneously

request_multiple(array $requests, array $options = array()) : array
Static

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 Requests constants). Same as the $type parameter to \Requests::request (string, default: Requests::GET)
  • cookies: Associative array of cookie name to value, or cookie jar. (array|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 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 Requests_Response/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

Requests data (see description for more information)

$options

array

Global and default options (see {@see Requests::request})

Returns

arrayResponses (either Requests_Response or a Requests_Exception object)

Set default certificate path.

set_certificate_path(string $path) 
Static

Parameters

$path

string

Certificate path, pointing to a PEM file.

Send a TRACE request

trace($url, $headers = array(), $options = array()) 
Static

Parameters

$url

$headers

$options

Decoded a chunked body as per RFC 2616

decode_chunked(string $data) : string
Static
see

Parameters

$data

string

Chunked body

Returns

stringDecoded body

Get the default options

get_default_options(boolean $multirequest = false) : array
Static
see for values returned by this method

Parameters

$multirequest

boolean

Is this a multirequest?

Returns

arrayDefault option values

Get a working transport

get_transport($capabilities = array()) : \Requests_Transport
Static

Parameters

$capabilities

Exceptions

\Requests_Exception If no valid transport is found (`notransport`)

Returns

\Requests_Transport

HTTP response parser

parse_response(string $headers, string $url, array $req_headers, array $req_data, array $options) : \Requests_Response
Static

Parameters

$headers

string

Full response text including headers and body

$url

string

Original request URL

$req_headers

array

Original $headers array passed to {@link request()}, in case we need to follow redirects

$req_data

array

Original $data array passed to {@link request()}, in case we need to follow redirects

$options

array

Original $options array passed to {@link request()}, in case we need to follow redirects

Exceptions

\Requests_Exception On missing head/body separator (`requests.no_crlf_separator`)
\Requests_Exception On missing head/body separator (`noversion`)
\Requests_Exception On missing head/body separator (`toomanyredirects`)

Returns

\Requests_Response

Set the default values

set_defaults(string $url, array $headers, array|null $data, string $type, array $options) : array
Static

Parameters

$url

string

URL to request

$headers

array

Extra headers to send with the request

$data

arraynull

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

Options for the request

Returns

array$options

This is a static class, do not instantiate it

__construct() 
codeCoverageIgnore

 Properties

 

Selected transport name

$transport : array

Default

array()
Static

Use \get_transport() instead

 

Default certificate path.

$certificate_path : string

Default

Static
see
see
 

Registered transport classes

$transports : array

Default

array()
Static

 Constants

 

Default size of buffer size to read streams

BUFFER_SIZE = 1160 : integer
 

DELETE method

DELETE = 'DELETE' : string
 

GET method

GET = 'GET' : string
 

HEAD method

HEAD = 'HEAD' : string
 

OPTIONS method

OPTIONS = 'OPTIONS' : string
 

PATCH method

PATCH = 'PATCH' : string
link https://tools.ietf.org/html/rfc5789
 

POST method

POST = 'POST' : string
 

PUT method

PUT = 'PUT' : string
 

TRACE method

TRACE = 'TRACE' : string
 

Current version of Requests

VERSION = '1.7-3470169' : string