A rudimentary HTTP client. More...

Inheritance diagram for Sabre\HTTP\Client:

Collaboration diagram for Sabre\HTTP\Client:

Public Member Functions
	__construct ()
	Initializes the client. More...

	send (RequestInterface $request)
	Sends a request to a HTTP server, and returns a response. More...

	sendAsync (RequestInterface $request, callable $success=null, callable $error=null)
	Sends a HTTP request asynchronously. More...

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

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

	setThrowExceptions ($throwExceptions)
	If this is set to true, the Client will automatically throw exceptions upon HTTP errors. More...

	addCurlSetting ($name, $value)
	Adds a CURL setting. More...

Public Member Functions inherited from Sabre\Event\EventEmitterInterface
	on ($eventName, callable $callBack, $priority=100)
	Subscribe to an event. More...

	once ($eventName, callable $callBack, $priority=100)
	Subscribe to an event exactly once. More...

	emit ($eventName, array $arguments=[], callable $continueCallBack=null)
	Emits an event. More...

	listeners ($eventName)
	Returns the list of listeners for an event. More...

	removeListener ($eventName, callable $listener)
	Removes a specific listener from an event. More...

	removeAllListeners ($eventName=null)
	Removes all listeners. More...

Data Fields
const	STATUS_SUCCESS = 0

const	STATUS_CURLERROR = 1

const	STATUS_HTTPERROR = 2

Protected Member Functions
	doRequest (RequestInterface $request)
	This method is responsible for performing a single request. More...

	createCurlSettingsArray (RequestInterface $request)
	Turns a RequestInterface object into an array with settings that can be fed to curl_setopt. More...

	parseCurlResult ($response, $curlHandle)
	Parses the result of a curl call in a format that's a bit more convenient to work with. More...

	sendAsyncInternal (RequestInterface $request, callable $success, callable $error, $retryCount=0)
	Sends an asynchronous HTTP request. More...

	curlExec ($curlHandle)
	Calls curl_exec. More...

	curlStuff ($curlHandle)
	Returns a bunch of information about a curl request. More...

Protected Attributes
	$curlSettings = []

	$throwExceptions = false

	$maxRedirects = 5

Private Attributes
	$curlHandle

	$curlMultiHandle

	$curlMultiMap = []

Detailed Description

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

Copyright: Copyright (C) fruux GmbH (https://fruux.com/)

Author: Evert Pot (http://evertpot.com/) @license http://sabre.io/license/ Modified BSD License

Definition at line 44 of file Client.php.

Constructor & Destructor Documentation

◆ __construct()

Sabre\HTTP\Client::__construct ( )

Initializes the client.

Returns: void

Definition at line 72 of file Client.php.

                           {
 
        $this->curlSettings = [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER         => true,
            CURLOPT_NOBODY         => false,
            CURLOPT_USERAGENT      => 'sabre-http/' . Version::VERSION . ' (http://sabre.io/)',
        ];
 
    }

References Sabre\HTTP\Version\VERSION.

Member Function Documentation

◆ addCurlSetting()

Sabre\HTTP\Client::addCurlSetting	(	$name,
		$value
	)

Adds a CURL setting.

These settings will be included in every HTTP request.

Parameters

int	$name
mixed	$value

Returns: void

Definition at line 331 of file Client.php.

                                           {
 
        $this->curlSettings[$name] = $value;
 
    }

References $name.

Referenced by Sabre\DAV\Client\__construct().

Here is the caller graph for this function:

◆ createCurlSettingsArray()

Sabre\HTTP\Client::createCurlSettingsArray ( RequestInterface $request )

protected

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

Parameters

RequestInterface $request

Returns: array

Reimplemented in Sabre\HTTP\ClientMock.

Definition at line 397 of file Client.php.

                                                                          {
 
        $settings = $this->curlSettings;
 
        switch ($request->getMethod()) {
            case 'HEAD' :
                $settings[CURLOPT_NOBODY] = true;
                $settings[CURLOPT_CUSTOMREQUEST] = 'HEAD';
                $settings[CURLOPT_POSTFIELDS] = '';
                $settings[CURLOPT_PUT] = false;
                break;
            case 'GET' :
                $settings[CURLOPT_CUSTOMREQUEST] = 'GET';
                $settings[CURLOPT_POSTFIELDS] = '';
                $settings[CURLOPT_PUT] = false;
                break;
            default :
                $body = $request->getBody();
                if (is_resource($body)) {
                    // This needs to be set to PUT, regardless of the actual
                    // method used. Without it, INFILE will be ignored for some
                    // reason.
                    $settings[CURLOPT_PUT] = true;
                    $settings[CURLOPT_INFILE] = $request->getBody();
                } else {
                    // For security we cast this to a string. If somehow an array could
                    // be passed here, it would be possible for an attacker to use @ to
                    // post local files.
                    $settings[CURLOPT_POSTFIELDS] = (string)$body;
                }
                $settings[CURLOPT_CUSTOMREQUEST] = $request->getMethod();
                break;
 
        }
 
        $nHeaders = [];
        foreach ($request->getHeaders() as $key => $values) {
 
            foreach ($values as $value) {
                $nHeaders[] = $key . ': ' . $value;
            }
 
        }
        $settings[CURLOPT_HTTPHEADER] = $nHeaders;
        $settings[CURLOPT_URL] = $request->getUrl();
        // FIXME: CURLOPT_PROTOCOLS is currently unsupported by HHVM
        if (defined('CURLOPT_PROTOCOLS')) {
            $settings[CURLOPT_PROTOCOLS] = CURLPROTO_HTTP | CURLPROTO_HTTPS;
        }
        // FIXME: CURLOPT_REDIR_PROTOCOLS is currently unsupported by HHVM
        if (defined('CURLOPT_REDIR_PROTOCOLS')) {
            $settings[CURLOPT_REDIR_PROTOCOLS] = CURLPROTO_HTTP | CURLPROTO_HTTPS;
        }
 
        return $settings;
 
    }

References Sabre\HTTP\Client\$curlSettings, $key, $request, and $values.

Referenced by Sabre\HTTP\Client\doRequest(), and Sabre\HTTP\Client\sendAsyncInternal().

Here is the caller graph for this function:

◆ curlExec()

Sabre\HTTP\Client::curlExec ( $curlHandle )

protected

Calls curl_exec.

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

Parameters

resource $curlHandle

Returns: string

Reimplemented in Sabre\HTTP\ClientMock.

Definition at line 576 of file Client.php.

                                             {
 
        return curl_exec($curlHandle);
 
    }

References Sabre\HTTP\Client\$curlHandle.

Referenced by Sabre\HTTP\Client\doRequest().

Here is the caller graph for this function:

◆ curlStuff()

Sabre\HTTP\Client::curlStuff ( $curlHandle )

protected

Returns a bunch of information about a curl request.

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

Parameters

resource $curlHandle

Returns: array

Reimplemented in Sabre\HTTP\ClientMock.

Definition at line 590 of file Client.php.

                                              {
 
        return [
            curl_getinfo($curlHandle),
            curl_errno($curlHandle),
            curl_error($curlHandle),
        ];
 
    }

References Sabre\HTTP\Client\$curlHandle.

Referenced by Sabre\HTTP\Client\parseCurlResult().

Here is the caller graph for this function:

◆ doRequest()

Sabre\HTTP\Client::doRequest ( RequestInterface $request )

protected

This method is responsible for performing a single request.

Parameters

RequestInterface $request

Returns: ResponseInterface

Reimplemented in Sabre\DAV\ClientMock, and Sabre\HTTP\ClientMock.

Definition at line 343 of file Client.php.

                                                            {
 
        $settings = $this->createCurlSettingsArray($request);
 
        if (!$this->curlHandle) {
            $this->curlHandle = curl_init();
        }
 
        curl_setopt_array($this->curlHandle, $settings);
        $response = $this->curlExec($this->curlHandle);
        $response = $this->parseCurlResult($response, $this->curlHandle);
 
        if ($response['status'] === self::STATUS_CURLERROR) {
            throw new ClientException($response['curl_errmsg'], $response['curl_errno']);
        }
 
        return $response['response'];
 
    }

References $response, Sabre\HTTP\Client\createCurlSettingsArray(), Sabre\HTTP\Client\curlExec(), and Sabre\HTTP\Client\parseCurlResult().

Referenced by Sabre\HTTP\Client\send().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parseCurlResult()

Sabre\HTTP\Client::parseCurlResult	(	$response,
		$curlHandle
	)

protected

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

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

string	$response
resource	$curlHandle

Returns: Response

Reimplemented in Sabre\HTTP\ClientMock.

Definition at line 478 of file Client.php.

                                                               {
 
        list(
            $curlInfo,
            $curlErrNo,
            $curlErrMsg
        ) = $this->curlStuff($curlHandle);
 
        if ($curlErrNo) {
            return [
                'status'      => self::STATUS_CURLERROR,
                'curl_errno'  => $curlErrNo,
                'curl_errmsg' => $curlErrMsg,
            ];
        }
 
        $headerBlob = substr($response, 0, $curlInfo['header_size']);
        // In the case of 204 No Content, strlen($response) == $curlInfo['header_size].
        // This will cause substr($response, $curlInfo['header_size']) return FALSE instead of NULL
        // An exception will be thrown when calling getBodyAsString then
        $responseBody = substr($response, $curlInfo['header_size']) ?: null;
 
        unset($response);
 
        // In the case of 100 Continue, or redirects we'll have multiple lists
        // of headers for each separate HTTP response. We can easily split this
        // because they are separated by \r\n\r\n
        $headerBlob = explode("\r\n\r\n", trim($headerBlob, "\r\n"));
 
        // We only care about the last set of headers
        $headerBlob = $headerBlob[count($headerBlob) - 1];
 
        // Splitting headers
        $headerBlob = explode("\r\n", $headerBlob);
 
        $response = new Response();
        $response->setStatus($curlInfo['http_code']);
 
        foreach ($headerBlob as $header) {
            $parts = explode(':', $header, 2);
            if (count($parts) == 2) {
                $response->addHeader(trim($parts[0]), trim($parts[1]));
            }
        }
 
        $response->setBody($responseBody);
 
        $httpCode = intval($response->getStatus());
 
        return [
            'status'    => $httpCode >= 400 ? self::STATUS_HTTPERROR : self::STATUS_SUCCESS,
            'response'  => $response,
            'http_code' => $httpCode,
        ];
 
    }

References Sabre\HTTP\Client\$curlHandle, $header, $response, Sabre\HTTP\Client\curlStuff(), Sabre\HTTP\Client\STATUS_CURLERROR, Sabre\HTTP\Client\STATUS_HTTPERROR, and Sabre\HTTP\Client\STATUS_SUCCESS.

Referenced by Sabre\HTTP\Client\doRequest(), and Sabre\HTTP\Client\poll().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ poll()

Sabre\HTTP\Client::poll ( )

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

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

Returns: bool

Definition at line 199 of file Client.php.

                    {
 
        // nothing to do?
        if (!$this->curlMultiMap) {
            return false;
        }
 
        do {
            $r = curl_multi_exec(
                $this->curlMultiHandle,
                $stillRunning
            );
        } while ($r === CURLM_CALL_MULTI_PERFORM);
 
        do {
 
            messageQueue:
 
            $status = curl_multi_info_read(
                $this->curlMultiHandle,
                $messagesInQueue
            );
 
            if ($status && $status['msg'] === CURLMSG_DONE) {
 
                $resourceId = intval($status['handle']);
                list(
                    $request,
                    $successCallback,
                    $errorCallback,
                    $retryCount,
                ) = $this->curlMultiMap[$resourceId];
                unset($this->curlMultiMap[$resourceId]);
                $curlResult = $this->parseCurlResult(curl_multi_getcontent($status['handle']), $status['handle']);
                $retry = false;
 
                if ($curlResult['status'] === self::STATUS_CURLERROR) {
 
                    $e = new ClientException($curlResult['curl_errmsg'], $curlResult['curl_errno']);
                    $this->emit('exception', [$request, $e, &$retry, $retryCount]);
 
                    if ($retry) {
                        $retryCount++;
                        $this->sendAsyncInternal($request, $successCallback, $errorCallback, $retryCount);
                        goto messageQueue;
                    }
 
                    $curlResult['request'] = $request;
 
                    if ($errorCallback) {
                        $errorCallback($curlResult);
                    }
 
                } elseif ($curlResult['status'] === self::STATUS_HTTPERROR) {
 
                    $this->emit('error', [$request, $curlResult['response'], &$retry, $retryCount]);
                    $this->emit('error:' . $curlResult['http_code'], [$request, $curlResult['response'], &$retry, $retryCount]);
 
                    if ($retry) {
 
                        $retryCount++;
                        $this->sendAsyncInternal($request, $successCallback, $errorCallback, $retryCount);
                        goto messageQueue;
 
                    }
 
                    $curlResult['request'] = $request;
 
                    if ($errorCallback) {
                        $errorCallback($curlResult);
                    }
 
                } else {
 
                    $this->emit('afterRequest', [$request, $curlResult['response']]);
 
                    if ($successCallback) {
                        $successCallback($curlResult['response']);
                    }
 
                }
            }
 
        } while ($messagesInQueue > 0);
 
        return count($this->curlMultiMap) > 0;
 
    }

References $r, $request, $retry, Sabre\Event\EventEmitterInterface\emit(), Sabre\HTTP\Client\parseCurlResult(), and Sabre\HTTP\Client\sendAsyncInternal().

Referenced by Sabre\HTTP\Client\sendAsync(), and Sabre\HTTP\Client\wait().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ send()

Sabre\HTTP\Client::send ( RequestInterface $request )

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

Parameters

RequestInterface $request

Returns: ResponseInterface

Definition at line 89 of file Client.php.

                                             {
 
        $this->emit('beforeRequest', [$request]);
 
        $retryCount = 0;
        $redirects = 0;
 
        do {
 
            $doRedirect = false;
            $retry = false;
 
            try {
 
                $response = $this->doRequest($request);
 
                $code = (int)$response->getStatus();
 
                // We are doing in-PHP redirects, because curl's
                // FOLLOW_LOCATION throws errors when PHP is configured with
                // open_basedir.
                //
                // https://github.com/fruux/sabre-http/issues/12
                if (in_array($code, [301, 302, 307, 308]) && $redirects < $this->maxRedirects) {
 
                    $oldLocation = $request->getUrl();
 
                    // Creating a new instance of the request object.
                    $request = clone $request;
 
                    // Setting the new location
                    $request->setUrl(Uri\resolve(
                        $oldLocation,
                        $response->getHeader('Location')
                    ));
 
                    $doRedirect = true;
                    $redirects++;
 
                }
 
                // This was a HTTP error
                if ($code >= 400) {
 
                    $this->emit('error', [$request, $response, &$retry, $retryCount]);
                    $this->emit('error:' . $code, [$request, $response, &$retry, $retryCount]);
 
                }
 
            } catch (ClientException $e) {
 
                $this->emit('exception', [$request, $e, &$retry, $retryCount]);
 
                // If retry was still set to false, it means no event handler
                // dealt with the problem. In this case we just re-throw the
                // exception.
                if (!$retry) {
                    throw $e;
                }
 
            }
 
            if ($retry) {
                $retryCount++;
            }
 
        } while ($retry || $doRedirect);
 
        $this->emit('afterRequest', [$request, $response]);
 
        if ($this->throwExceptions && $code >= 400) {
            throw new ClientHttpException($response);
        }
 
        return $response;
 
    }

References $code, Sabre\HTTP\Client\$maxRedirects, $request, $response, $retry, Sabre\HTTP\Client\doRequest(), Sabre\Event\EventEmitterInterface\emit(), and Sabre\Event\Promise\resolve().

Referenced by Sabre\DAV\Client\options(), Sabre\DAV\Client\propFind(), Sabre\DAV\Client\propPatch(), and Sabre\DAV\Client\request().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sendAsync()

Sabre\HTTP\Client::sendAsync	(	RequestInterface	$request,
		callable	$success = `null`,
		callable	$error = `null`
	)

Sends a HTTP request asynchronously.

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

RequestInterface	$request
callable	$success
callable	$error

Returns: void

Definition at line 181 of file Client.php.

                                                                                                    {
 
        $this->emit('beforeRequest', [$request]);
        $this->sendAsyncInternal($request, $success, $error);
        $this->poll();
 
    }

References $success, Sabre\Event\EventEmitterInterface\emit(), Sabre\HTTP\Client\poll(), and Sabre\HTTP\Client\sendAsyncInternal().

Here is the call graph for this function:

◆ sendAsyncInternal()

Sabre\HTTP\Client::sendAsyncInternal	(	RequestInterface	$request,
		callable	$success,
		callable	$error,
			$retryCount = `0`
	)

protected

Sends an asynchronous HTTP request.

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

Parameters

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

Definition at line 546 of file Client.php.

                                                                                                                         {
 
        if (!$this->curlMultiHandle) {
            $this->curlMultiHandle = curl_multi_init();
        }
        $curl = curl_init();
        curl_setopt_array(
            $curl,
            $this->createCurlSettingsArray($request)
        );
        curl_multi_add_handle($this->curlMultiHandle, $curl);
        $this->curlMultiMap[intval($curl)] = [
            $request,
            $success,
            $error,
            $retryCount
        ];
 
    }

References $request, $success, and Sabre\HTTP\Client\createCurlSettingsArray().

Referenced by Sabre\HTTP\Client\poll(), and Sabre\HTTP\Client\sendAsync().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setThrowExceptions()

Sabre\HTTP\Client::setThrowExceptions ( $throwExceptions )

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

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

bool $throwExceptions

Returns: void

Definition at line 316 of file Client.php.

                                                  {
 
        $this->throwExceptions = $throwExceptions;
 
    }

References Sabre\HTTP\Client\$throwExceptions.

◆ wait()

Sabre\HTTP\Client::wait ( )

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

Returns: void

Definition at line 294 of file Client.php.

                    {
 
        do {
            curl_multi_select($this->curlMultiHandle);
            $stillRunning = $this->poll();
        } while ($stillRunning);
 
    }

References Sabre\HTTP\Client\poll().

Here is the call graph for this function:

Field Documentation

◆ $curlHandle

Sabre\HTTP\Client::$curlHandle

private

Definition at line 371 of file Client.php.

Referenced by Sabre\HTTP\Client\curlExec(), Sabre\HTTP\ClientMock\curlExec(), Sabre\HTTP\Client\curlStuff(), Sabre\HTTP\ClientMock\curlStuff(), Sabre\HTTP\Client\parseCurlResult(), and Sabre\HTTP\ClientMock\parseCurlResult().

◆ $curlMultiHandle

Sabre\HTTP\Client::$curlMultiHandle

private

Definition at line 380 of file Client.php.

◆ $curlMultiMap

Sabre\HTTP\Client::$curlMultiMap = []

private

Definition at line 388 of file Client.php.

◆ $curlSettings

Sabre\HTTP\Client::$curlSettings = []

protected

Definition at line 51 of file Client.php.

Referenced by Sabre\HTTP\Client\createCurlSettingsArray().

◆ $maxRedirects

Sabre\HTTP\Client::$maxRedirects = 5

protected

Definition at line 65 of file Client.php.

Referenced by Sabre\HTTP\Client\send().

◆ $throwExceptions

Sabre\HTTP\Client::$throwExceptions = false

protected

Definition at line 58 of file Client.php.

Referenced by Sabre\HTTP\Client\setThrowExceptions().

◆ STATUS_CURLERROR

const Sabre\HTTP\Client::STATUS_CURLERROR = 1

Definition at line 456 of file Client.php.

Referenced by Sabre\HTTP\Client\parseCurlResult(), and Sabre\HTTP\ClientTest\testParseCurlError().

◆ STATUS_HTTPERROR

const Sabre\HTTP\Client::STATUS_HTTPERROR = 2

Definition at line 457 of file Client.php.

Referenced by Sabre\HTTP\Client\parseCurlResult().

◆ STATUS_SUCCESS

const Sabre\HTTP\Client::STATUS_SUCCESS = 0

Definition at line 455 of file Client.php.

Referenced by Sabre\HTTP\Client\parseCurlResult(), and Sabre\HTTP\ClientTest\testParseCurlResult().

The documentation for this class was generated from the following file:

libs/composer/vendor/sabre/http/lib/Client.php

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addCurlSetting()

◆ createCurlSettingsArray()

◆ curlExec()

◆ curlStuff()

◆ doRequest()

◆ parseCurlResult()

◆ poll()

◆ send()

◆ sendAsync()

◆ sendAsyncInternal()

◆ setThrowExceptions()

◆ wait()

Field Documentation

◆ $curlHandle

◆ $curlMultiHandle

◆ $curlMultiMap

◆ $curlSettings

◆ $maxRedirects

◆ $throwExceptions

◆ STATUS_CURLERROR

◆ STATUS_HTTPERROR

◆ STATUS_SUCCESS