Using Guzzle promises asyncronously

In Guzzle (the underlying HTTP client library that Laravel’s HTTP client is built on), GuzzleHttp\Promise is the component that implements the Promises/A+ specification. In practice, it lets you work with HTTP requests (and any other asynchronous tasks) in a non‑blocking, “promise‑based” fashion:

Promise: Represents the eventual result of an asynchronous operation.
PromiseInterface: Defines methods like then(), otherwise(), and wait().
Utils: Helpers for combining or settling multiple promises (Utils::all(), Utils::settle(), Utils::eachLimit(), etc.).

How it fits into Laravel

Laravel’s fluent HTTP client (Illuminate\Support\Facades\Http) is a thin layer over Guzzle, so:

By default, requests are synchronous:

$response = Http::get('https://api.example.com/users/1');

Under the hood, that’s equivalent to creating a Guzzle promise and immediately calling ->wait() on it.

If you want concurrent (parallel) requests, Laravel exposes Guzzle’s promise machinery via the pool() method:

use Illuminate\Support\Facades\Http;

$responses = Http::pool(fn (Illuminate\Http\Client\Pool $pool) => [
    $pool->get('https://api.example.com/users/1'),
    $pool->get('https://api.example.com/users/2'),
    $pool->get('https://api.example.com/users/3'),
]);

// $responses is an array of Response instances, in the order of the pool calls
foreach ($responses as $response) {
    echo $response->body();
}

Behind the scenes, each $pool->get(...) returns a Guzzle promise. Laravel waits on all of them concurrently for you, then gives you the array of fulfilled responses.

Working with Guzzle Promises directly

If you need finer control, you can pull in Guzzle’s promise namespace yourself:

use GuzzleHttp\Client;
use GuzzleHttp\Promise;

$client = new Client();

// Create a couple of promises...
$promises = [
    'github' => $client->getAsync('https://api.github.com/users/guzzle'),
    'laravel' => $client->getAsync('https://laravel.com'),
];

// Wait for all of them to complete.
$results = Promise\Utils::settle($promises)->wait();

// Inspect each result
foreach ($results as $key => $result) {
    if ($result['state'] === 'fulfilled') {
        echo strtoupper($key) . " returned " . $result['value']->getStatusCode() . "\n";
    } else {
        echo strtoupper($key) . " failed: " . $result['reason']->getMessage() . "\n";
    }
}

Key methods on a promise

then(callable $onFulfilled, callable $onRejected = null): chain a callback for success (and optionally for failure).
otherwise(callable $onRejected): shorthand to attach only a rejection handler.
wait(): block until the promise resolves or rejects, then return the value (or throw on error).

When to use it in Laravel

Parallel HTTP calls: use Http::pool() for simple cases, or dive into Guzzle promises directly for more complex orchestration.
Background jobs & long polling: you might create promises for non‑HTTP tasks (e.g. database queries or file uploads) and resolve them later.
Performance optimization: bundling many external requests into concurrent groups can drastically reduce total latency.

Bottom line

Guzzle’s Promise library underpins Laravel’s ability to dispatch and manage asynchronous HTTP requests. When you need concurrency, resilience (retrying, fallback), or complex coordination of multiple calls, learn the basics of GuzzleHttp\Promise and you’ll unlock much more powerful HTTP workflows in your Laravel applications.

SRE School