Simple, async PSR-7 HTTP client for concurrently processing any number of HTTP requests, built on top of ReactPHP.
This library is heavily inspired by the great kriswallsmith/Buzz project. However, instead of blocking on each request, it relies on ReactPHP's EventLoop to process multiple requests in parallel. This allows you to interact with multiple HTTP servers (fetch URLs, talk to RESTful APIs, follow redirects etc.) at the same time. Unlike the underlying react/http-client, this project aims at providing a higher-level API that is easy to use in order to process multiple HTTP requests concurrently without having to mess with most of the low-level details.
- Async execution of HTTP requests - Send any number of HTTP requests to any number of HTTP servers in parallel and process their responses as soon as results come in. The Promise-based design provides a sane interface to working with out of bound responses.
- Lightweight, SOLID design - Provides a thin abstraction that is just good enough and does not get in your way. Builds on top of well-tested components and well-established concepts instead of reinventing the wheel.
- Good test coverage - Comes with an automated tests suite and is regularly tested in the real world
Table of contents
Once installed, you can use the following code to access a HTTP webserver and send some simple HTTP GET requests:
$loop = React\EventLoop\Factory::create();
$client = new Browser($loop);
$client->get('http://www.google.com/')->then(function (ResponseInterface $response) {
var_dump($response->getHeaders(), (string)$response->getBody());
});
$loop->run();See also the examples.
The Browser is responsible for sending HTTP requests to your HTTP server
and keeps track of pending incoming HTTP responses.
It also registers everything with the main EventLoop.
$loop = React\EventLoop\Factory::create();
$browser = new Browser($loop);If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
proxy servers etc.), you can explicitly pass a custom instance of the
ConnectorInterface:
$connector = new \React\Socket\Connector($loop, array(
'dns' => '127.0.0.1',
'tcp' => array(
'bindto' => '192.168.10.1:0'
),
'tls' => array(
'verify_peer' => false,
'verify_peer_name' => false
)
));
$browser = new Browser($loop, $connector);The Browser offers several methods that resemble the HTTP protocol methods:
$browser->get($url, array $headers = array());
$browser->head($url, array $headers = array());
$browser->post($url, array $headers = array(), $content = '');
$browser->delete($url, array $headers = array(), $content = '');
$browser->put($url, array $headers = array(), $content = '');
$browser->patch($url, array $headers = array(), $content = '');All the above methods default to sending requests as HTTP/1.0.
If you need a custom HTTP protocol method or version, you can use the send() method.
Each of the above methods supports async operation and either resolves with a ResponseInterface or
rejects with an Exception.
Please see the following chapter about promises for more details.
Sending requests is async (non-blocking), so you can actually send multiple requests in parallel.
The Browser will respond to each request with a ResponseInterface message, the order is not guaranteed.
Sending requests uses a Promise-based interface that makes it easy to react to when a transaction is fulfilled (i.e. either successfully resolved or rejected with an error):
$browser->get($url)->then(
function (ResponseInterface $response) {
var_dump('Response received', $response);
},
function (Exception $error) {
var_dump('There was an error', $error->getMessage());
}
);If this looks strange to you, you can also use the more traditional blocking API.
Keep in mind that resolving the Promise with the full response message means the whole response body has to be kept in memory. This is easy to get started and works reasonably well for smaller responses (such as common HTML pages or RESTful or JSON API requests).
You may also want to look into the streaming API:
- If you're dealing with lots of concurrent requests (100+) or
- If you want to process individual data chunks as they happen (without having to wait for the full response body) or
- If you're expecting a big response body size (1 MiB or more, for example when downloading binary files) or
- If you're unsure about the response body size (better be safe than sorry when accessing arbitrary remote HTTP endpoints and the response body size is unknown in advance).
The returned Promise is implemented in such a way that it can be cancelled when it is still pending. Cancelling a pending promise will reject its value with an Exception and clean up any underlying resources.
$promise = $browser->get($url);
$loop->addTimer(2.0, function () use ($promise) {
$promise->cancel();
});As stated above, this library provides you a powerful, async API by default.
If, however, you want to integrate this into your traditional, blocking environment, you should look into also using clue/block-react.
The resulting blocking code could look something like this:
use Clue\React\Block;
$loop = React\EventLoop\Factory::create();
$browser = new Clue\React\Buzz\Browser($loop);
$promise = $browser->get('http://example.com/');
try {
$response = Block\await($promise, $loop);
// response successfully received
} catch (Exception $e) {
// an error occured while performing the request
}Similarly, you can also process multiple requests concurrently and await an array of Response objects:
$promises = array(
$browser->get('http://example.com/'),
$browser->get('http://www.example.org/'),
);
$responses = Block\awaitAll($promises, $loop);Please refer to clue/block-react for more details.
Keep in mind the above remark about buffering the whole response message in memory. As an alternative, you may also see the following chapter for the streaming API.
All of the above examples assume you want to store the whole response body in memory. This is easy to get started and works reasonably well for smaller responses.
However, there are several situations where it's usually a better idea to use a streaming approach, where only small chunks have to be kept in memory:
- If you're dealing with lots of concurrent requests (100+) or
- If you want to process individual data chunks as they happen (without having to wait for the full response body) or
- If you're expecting a big response body size (1 MiB or more, for example when downloading binary files) or
- If you're unsure about the response body size (better be safe than sorry when accessing arbitrary remote HTTP endpoints and the response body size is unknown in advance).
The streaming API uses the same HTTP message API, but does not buffer the response message body in memory. It only processes the response body in small chunks as data is received and forwards this data through React's Stream API. This works for (any number of) responses of arbitrary sizes.
This resolves with a normal ResponseInterface, which
can be used to access the response message parameters as usual.
You can access the message body as usual, however it now also
implements ReactPHP's ReadableStreamInterface
as well as parts of the PSR-7's StreamInterface.
// turn on streaming responses (does no longer buffer response body)
$streamingBrowser = $browser->withOptions(array('streaming' => true));
// issue a normal GET request
$streamingBrowser->get($url)->then(function (ResponseInterface $response) {
$body = $response->getBody();
/* @var $body \React\Stream\ReadableStreamInterface */
$body->on('data', function ($chunk) {
echo $chunk;
});
$body->on('error', function (Exception $error) {
echo 'Error: ' . $error->getMessage() . PHP_EOL;
});
$body->on('close', function () {
echo '[DONE]' . PHP_EOL;
});
});See also the stream bandwidth example and the stream forwarding example.
You can invoke the following methods on the message body:
$body->on($event, $callback);
$body->eof();
$body->isReadable();
$body->pipe(WritableStreamInterface $dest, array $options = array());
$body->close();
$body->pause();
$body->resume();Because the message body is in a streaming state, invoking the following methods doesn't make much sense:
$body->__toString(); // ''
$body->detach(); // throws BadMethodCallException
$body->getSize(); // null
$body->tell(); // throws BadMethodCallException
$body->isSeekable(); // false
$body->seek(); // throws BadMethodCallException
$body->rewind(); // throws BadMethodCallException
$body->isWritable(); // false
$body->write(); // throws BadMethodCallException
$body->read(); // throws BadMethodCallException
$body->getContents(); // throws BadMethodCallExceptionIf you want to integrate the streaming response into a higher level API, then working with Promise objects that resolve with Stream objects is often inconvenient. Consider looking into also using react/promise-stream. The resulting streaming code could look something like this:
use React\Promise\Stream;
function download($url) {
return Stream\unwrapReadable($streamingBrowser->get($url)->then(function (ResponseInterface $response) {
return $response->getBody();
});
}
$stream = download($url);
$stream->on('data', function ($data) {
echo $data;
});Besides streaming the response body, you can also stream the request body.
This can be useful if you want to send big POST requests (uploading files etc.)
or process many outgoing streams at once.
Instead of passing the body as a string, you can simply pass an instance
implementing ReactPHP's ReadableStreamInterface
to the HTTP methods like this:
$browser->post($url, array(), $stream)->then(function (ResponseInterface $response) {
echo 'Successfully sent.';
});The submit($url, array $fields, $headers = array(), $method = 'POST') method can be used to submit an array of field values similar to submitting a form (application/x-www-form-urlencoded).
The send(RequestInterface $request) method can be used to send an arbitrary
instance implementing the RequestInterface (PSR-7).
All the above predefined methods default to sending requests as HTTP/1.0. If you need a custom HTTP protocol method or version, then you may want to use this method:
$request = new Request('OPTIONS', $url);
$request = $request->withProtocolVersion(1.1);
$browser->send($request)->then(…);The withOptions(array $options) method can be used to change the options to use:
$newBrowser = $browser->withOptions($options);Notice that the Browser is an immutable object, i.e. the withOptions() method
actually returns a new Browser instance with the options applied.
See options for more details.
The withBase($baseUri) method can be used to change the base URI used to
resolve relative URIs to.
$newBrowser = $browser->withBase('http://api.example.com/v3');Notice that the Browser is an immutable object, i.e. the withBase() method
actually returns a new Browser instance with the given base URI applied.
Any requests to relative URIs will then be processed by first prepending the
base URI.
Please note that this merely prepends the base URI and does not resolve any
relative path references (like ../ etc.).
This is mostly useful for API calls where all endpoints (URIs) are located
under a common base URI scheme.
// will request http://api.example.com/v3/example
$newBrowser->get('/example')->then(…);The withoutBase() method can be used to remove the base URI.
$newBrowser = $browser->withoutBase();Notice that the Browser is an immutable object, i.e. the withoutBase() method
actually returns a new Browser instance without any base URI applied.
See also withBase().
The Psr\Http\Message\ResponseInterface represents the incoming response received from the Browser.
This is a standard interface defined in
PSR-7: HTTP message interfaces, see its
ResponseInterface definition
which in turn extends the
MessageInterface definition.
The Psr\Http\Message\RequestInterface represents the outgoing request to be sent via the Browser.
This is a standard interface defined in
PSR-7: HTTP message interfaces, see its
RequestInterface definition
which in turn extends the
MessageInterface definition.
The Psr\Http\Message\UriInterface represents an absolute or relative URI (aka URL).
This is a standard interface defined in
PSR-7: HTTP message interfaces, see its
UriInterface definition.
The ResponseException is an Exception sub-class that will be used to reject
a request promise if the remote server returns a non-success status code
(anything but 2xx or 3xx).
You can control this behavior via the "obeySuccessCode" option.
The getCode() method can be used to return the HTTP response status code.
The getResponse() method can be used to access its underlying ResponseInteface object.
You can also establish your outgoing connections through a SOCKS proxy server by adding a dependency to clue/socks-react.
The SOCKS protocol operates at the TCP/IP layer and thus requires minimal effort at the HTTP application layer. This works for both plain HTTP and SSL encrypted HTTPS requests.
See also the SOCKS example.
By default, this library supports transport over plaintext TCP/IP and secure
TLS connections for the http:// and https:// URI schemes respectively.
This library also supports Unix domain sockets (UDS) when explicitly configured.
In order to use a UDS path, you have to explicitly configure the connector to override the destination URI so that the hostname given in the request URI will no longer be used to establish the connection:
$connector = new \React\Socket\FixedUriConnector(
'unix:///var/run/docker.sock',
new \React\Socket\UnixConnector($loop)
);
$browser = new Browser($loop, $connector);
$client->get('http://localhost/info')->then(function (ResponseInterface $response) {
var_dump($response->getHeaders(), (string)$response->getBody());
});See also the Unix Domain Sockets (UDS) example.
The Browser class exposes several options for the handling of
HTTP transactions. These options resemble some of PHP's
HTTP context options and
can be controlled via the following API (and their defaults):
$newBrowser = $browser->withOptions(array(
'followRedirects' => true,
'maxRedirects' => 10,
'obeySuccessCode' => true,
'streaming' => false,
));Notice that the Browser is an immutable object, i.e. the withOptions() method
actually returns a new Browser instance with the options applied.
The recommended way to install this library is through Composer. New to Composer?
This project follows SemVer. This will install the latest supported version:
$ composer require clue/buzz-react:^2.2See also the CHANGELOG for details about version upgrades.
This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.4 through current PHP 7+ and HHVM. It's highly recommended to use PHP 7+ for this project.
To run the test suite, you first need to clone this repo and then install all dependencies through Composer:
$ composer installTo run the test suite, go to the project root and run:
$ php vendor/bin/phpunitThe test suite also contains a number of functional integration tests that send test HTTP requests against the online service http://httpbin.org and thus rely on a stable internet connection. If you do not want to run these, they can simply be skipped like this:
$ php vendor/bin/phpunit --exclude-group onlineMIT