Documentation

Sabre
HTTP

Client extends EventEmitter
in package

Application

A rudimentary HTTP client.

This object wraps PHP's curl extension and provides an easy way to send it a Request object, and return a Response object.

This is by no means intended as the next best HTTP client, but it does the job and provides a simple integration with the rest of sabre/http.

This client emits the following events: beforeRequest(RequestInterface $request) afterRequest(RequestInterface $request, ResponseInterface $response) error(RequestInterface $request, ResponseInterface $response, bool &$retry, int $retryCount) exception(RequestInterface $request, ClientException $e, bool &$retry, int $retryCount)

The beforeRequest event allows you to do some last minute changes to the request before it's done, such as adding authentication headers.

The afterRequest event will be emitted after the request is completed succesfully.

If a HTTP error is returned (status code higher than 399) the error event is triggered. It's possible using this event to retry the request, by setting retry to true.

The amount of times a request has retried is passed as $retryCount, which can be used to avoid retrying indefinitely. The first time the event is called, this will be 0.

It's also possible to intercept specific http errors, by subscribing to for example 'error:401'.

STATUS_CURLERROR


    public
    mixed
    STATUS_CURLERROR
    = 1

STATUS_HTTPERROR


    public
    mixed
    STATUS_HTTPERROR
    = 2

STATUS_SUCCESS


    public
    mixed
    STATUS_SUCCESS
    = 0

$curlSettings

List of curl settings.


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

$headerLinesMap


    protected
        mixed
    $headerLinesMap
     = []

$listeners

The list of listeners.


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

$maxRedirects

The maximum number of times we'll follow a redirect.


    protected
        int
    $maxRedirects
     = 5

$throwExceptions

Wether or not exceptions should be thrown when a HTTP error is returned.


    protected
        bool
    $throwExceptions
     = false

$curlHandle

Cached curl handle.


    private
        resource
    $curlHandle

By keeping this resource around for the lifetime of this object, things like persistent connections are possible.

$curlMultiHandle

Handler for curl_multi requests.


    private
        resource
    $curlMultiHandle

The first time sendAsync is used, this will be created.

$curlMultiMap

Has a list of curl handles, as well as their associated success and error callbacks.


    private
        array<string|int, mixed>
    $curlMultiMap
     = []

__construct()

Initializes the client.


    public
                __construct() : mixed

Return values

mixed —

addCurlSetting()

Adds a CURL setting.


    public
                addCurlSetting(int $name, mixed $value) : mixed

These settings will be included in every HTTP request.

Parameters

$name : int
$value : mixed

Return values

mixed —

emit()

Emits an event.


    public
                emit(string $eventName[, array<string|int, mixed> $arguments = [] ][, callable $continueCallBack = null ]) : bool

This method will return true if 0 or more listeners were successfully handled. false is returned if one of the events broke the event chain.

If the continueCallBack is specified, this callback will be called every time before the next event handler is called.

If the continueCallback returns false, event propagation stops. This allows you to use the eventEmitter as a means for listeners to implement functionality in your application, and break the event loop as soon as some condition is fulfilled.

Note that returning false from an event subscriber breaks propagation and returns false, but if the continue-callback stops propagation, this is still considered a 'successful' operation and returns true.

Lastly, if there are 5 event handlers for an event. The continueCallback will be called at most 4 times.

Parameters

$eventName : string
$arguments : array<string|int, mixed> = []
$continueCallBack : callable = null

Return values

bool —

listeners()

Returns the list of listeners for an event.


    public
                listeners(string $eventName) : array<string|int, callable>

The list is returned as an array, and the list of events are sorted by their priority.

Parameters

$eventName : string

Return values

array<string|int, callable> —

on()

Subscribe to an event.


    public
                on(string $eventName, callable $callBack[, int $priority = 100 ]) : mixed

Parameters

$eventName : string
$callBack : callable
$priority : int = 100

Return values

mixed —

once()

Subscribe to an event exactly once.


    public
                once(string $eventName, callable $callBack[, int $priority = 100 ]) : mixed

Parameters

$eventName : string
$callBack : callable
$priority : int = 100

Return values

mixed —

poll()

This method checks if any http requests have gotten results, and if so, call the appropriate success or error handlers.


    public
                poll() : bool

This method will return true if there are still requests waiting to return, and false if all the work is done.

Return values

bool —

removeAllListeners()

Removes all listeners.


    public
                removeAllListeners([string $eventName = null ]) : mixed

If the eventName argument is specified, all listeners for that event are removed. If it is not specified, every listener for every event is removed.

Parameters

$eventName : string = null

Return values

mixed —

removeListener()

Removes a specific listener from an event.


    public
                removeListener(string $eventName, callable $listener) : bool

If the listener could not be found, this method will return false. If it was removed it will return true.

Parameters

$eventName : string
$listener : callable

Return values

bool —

send()

Sends a request to a HTTP server, and returns a response.


    public
                send(RequestInterface $request) : ResponseInterface

Parameters

$request : RequestInterface

Return values

ResponseInterface —

sendAsync()

Sends a HTTP request asynchronously.


    public
                sendAsync(RequestInterface $request[, callable $success = null ][, callable $error = null ]) : mixed

Due to the nature of PHP, you must from time to time poll to see if any new responses came in.

After calling sendAsync, you must therefore occasionally call the poll() method, or wait().

Parameters

$request : RequestInterface
$success : callable = null
$error : callable = null

Return values

mixed —

setThrowExceptions()

If this is set to true, the Client will automatically throw exceptions upon HTTP errors.


    public
                setThrowExceptions(bool $throwExceptions) : mixed

This means that if a response came back with a status code greater than or equal to 400, we will throw a ClientHttpException.

This only works for the send() method. Throwing exceptions for sendAsync() is not supported.

Parameters

$throwExceptions : bool

Return values

mixed —

wait()

Processes every HTTP request in the queue, and waits till they are all completed.


    public
                wait() : mixed

Return values

mixed —

createCurlSettingsArray()

Turns a RequestInterface object into an array with settings that can be fed to curl_setopt.


    protected
                createCurlSettingsArray(RequestInterface $request) : array<string|int, mixed>

Parameters

$request : RequestInterface

Return values

array<string|int, mixed> —

curlExec()

Calls curl_exec.


    protected
                curlExec(resource $curlHandle) : string

This method exists so it can easily be overridden and mocked.

Parameters

$curlHandle : resource

Return values

string —

curlStuff()

Returns a bunch of information about a curl request.


    protected
                curlStuff(resource $curlHandle) : array<string|int, mixed>

This method exists so it can easily be overridden and mocked.

Parameters

$curlHandle : resource

Return values

array<string|int, mixed> —

doRequest()

This method is responsible for performing a single request.


    protected
                doRequest(RequestInterface $request) : ResponseInterface

Parameters

$request : RequestInterface

Return values

ResponseInterface —

parseCurlResponse()

Parses the result of a curl call in a format that's a bit more convenient to work with.


    protected
                parseCurlResponse(array<string|int, mixed> $headerLines, string $body, resource $curlHandle) : array<string|int, mixed>

The method returns an array with the following elements:

status - one of the 3 STATUS constants.
curl_errno - A curl error number. Only set if status is STATUS_CURLERROR.
curl_errmsg - A current error message. Only set if status is STATUS_CURLERROR.
response - Response object. Only set if status is STATUS_SUCCESS, or STATUS_HTTPERROR.
http_code - HTTP status code, as an int. Only set if Only set if status is STATUS_SUCCESS, or STATUS_HTTPERROR

Parameters

$headerLines : array<string|int, mixed>
$body : string
$curlHandle : resource

Return values

array<string|int, mixed> —

parseCurlResult()

Parses the result of a curl call in a format that's a bit more convenient to work with.


    protected
                parseCurlResult(string $response, resource $curlHandle) : array<string|int, mixed>

The method returns an array with the following elements:

status - one of the 3 STATUS constants.
curl_errno - A curl error number. Only set if status is STATUS_CURLERROR.
curl_errmsg - A current error message. Only set if status is STATUS_CURLERROR.
response - Response object. Only set if status is STATUS_SUCCESS, or STATUS_HTTPERROR.
http_code - HTTP status code, as an int. Only set if Only set if status is STATUS_SUCCESS, or STATUS_HTTPERROR

Parameters

$response : string
$curlHandle : resource

Return values

array<string|int, mixed> —

receiveCurlHeader()


    protected
                receiveCurlHeader(mixed $curlHandle, mixed $headerLine) : mixed

Parameters

$curlHandle : mixed
$headerLine : mixed

Return values

mixed —

sendAsyncInternal()

Sends an asynchronous HTTP request.


    protected
                sendAsyncInternal(RequestInterface $request, callable $success, callable $error, int $retryCount) : mixed

We keep this in a separate method, so we can call it without triggering the beforeRequest event and don't do the poll().

Parameters

$request : RequestInterface
$success : callable
$error : callable
$retryCount : int

Return values

mixed —

parseResponse()


    private
                parseResponse(string $response, mixed $curlHandle) : array<string|int, mixed>

Parameters

$response : string
$curlHandle : mixed

Return values

array<string|int, mixed> —