Sending Requests With a Pool

You can send requests concurrently using a fixed size pool via the GuzzleHttp\Pool class. The Pool class is an implementation of GuzzleHttp\Ring\Future\FutureInterface, meaning it can be dereferenced at a later time or cancelled before sending. The Pool constructor accepts a client object, iterator or array that yields GuzzleHttp\Message\RequestInterface objects, and an optional associative array of options that can be used to affect the transfer.

use GuzzleHttp\Pool;
$requests = [
    $client->createRequest('GET', 'http://httpbin.org'),
    $client->createRequest('DELETE', 'http://httpbin.org/delete'),
    $client->createRequest('PUT', 'http://httpbin.org/put', ['body' => 'test'])
];
$options = [];
// Create a pool. Note: the options array is optional.
$pool = new Pool($client, $requests, $options);
// Send the requests
$pool->wait();

The Pool constructor accepts the following associative array of options:

• pool_size: Integer representing the maximum number of requests that are allowed to be sent concurrently.
• before: Callable or array representing the event listeners to add to each request’s before event.
• complete: Callable or array representing the event listeners to add to each request’s complete event.
• error: Callable or array representing the event listeners to add to each request’s error event.
• end: Callable or array representing the event listeners to add to each request’s end event.

The “before”, “complete”, “error”, and “end” event options accept a callable or an array of associative arrays where each associative array contains a “fn” key with a callable value, an optional “priority” key representing the event priority (with a default value of 0), and an optional “once” key that can be set to true so that the event listener will be removed from the request after it is first triggered.

use GuzzleHttp\Pool;
use GuzzleHttp\Event\CompleteEvent;
// Add a single event listener using a callable.
Pool::send($client, $requests, [
    'complete' => function (CompleteEvent $event) {
        echo 'Completed request to ' . $event->getRequest()->getUrl() . "\n";
        echo 'Response: ' . $event->getResponse()->getBody() . "\n\n";
    }
]);
// The above is equivalent to the following, but the following structure
// allows you to add multiple event listeners to the same event name.
Pool::send($client, $requests, [
    'complete' => [
        [
            'fn'       => function (CompleteEvent $event) { /* ... */ },
            'priority' => 0,    // Optional
            'once'     => false // Optional
        ]
    ]
]);

Asynchronous Response Handling

When sending requests concurrently using a pool, the request/response/error lifecycle must be handled asynchronously. This means that you give the Pool multiple requests and handle the response or errors that is associated with the request using event callbacks.

use GuzzleHttp\Pool;
use GuzzleHttp\Event\ErrorEvent;
Pool::send($client, $requests, [
    'complete' => function (CompleteEvent $event) {
        echo 'Completed request to ' . $event->getRequest()->getUrl() . "\n";
        echo 'Response: ' . $event->getResponse()->getBody() . "\n\n";
        // Do something with the completion of the request...
    },
    'error' => function (ErrorEvent $event) {
        echo 'Request failed: ' . $event->getRequest()->getUrl() . "\n";
        echo $event->getException();
        // Do something to handle the error...
    }
]);

The GuzzleHttp\Event\ErrorEvent event object is emitted when an error occurs during a transfer. With this event, you have access to the request that was sent, the response that was received (if one was received), access to transfer statistics, and the ability to intercept the exception with a different GuzzleHttp\Message\ResponseInterface object. See Event System for more information.

Handling Errors After Transferring

It sometimes might be easier to handle all of the errors that occurred during a transfer after all of the requests have been sent. Here we are adding each failed request to an array that we can use to process errors later.

use GuzzleHttp\Pool;
use GuzzleHttp\Event\ErrorEvent;
$errors = [];
Pool::send($client, $requests, [
    'error' => function (ErrorEvent $event) use (&$errors) {
        $errors[] = $event;
    }
]);
foreach ($errors as $error) {
    // Handle the error...
}

Batching Requests

Sometimes you just want to send a few requests concurrently and then process the results all at once after they’ve been sent. Guzzle provides a convenience function GuzzleHttp\Pool::batch() that makes this very simple:

use GuzzleHttp\Pool;
use GuzzleHttp\Client;
$client = new Client();
$requests = [
    $client->createRequest('GET', 'http://httpbin.org/get'),
    $client->createRequest('HEAD', 'http://httpbin.org/get'),
    $client->createRequest('PUT', 'http://httpbin.org/put'),
];
// Results is a GuzzleHttp\BatchResults object.
$results = Pool::batch($client, $requests);
// Can be accessed by index.
echo $results[0]->getStatusCode();
// Can be accessed by request.
echo $results->getResult($requests[0])->getStatusCode();
// Retrieve all successful responses
foreach ($results->getSuccessful() as $response) {
    echo $response->getStatusCode() . "\n";
}
// Retrieve all failures.
foreach ($results->getFailures() as $requestException) {
    echo $requestException->getMessage() . "\n";
}

GuzzleHttp\Pool::batch() accepts an optional associative array of options in the third argument that allows you to specify the ‘before’, ‘complete’, ‘error’, and ‘end’ events as well as specify the maximum number of requests to send concurrently using the ‘pool_size’ option key.