← Back to glossary

Promises & Futures

concurrency PHP 7.0+ Intermediate

Also Known As

Promise Future async promise deferred then/catch PromiseInterface

TL;DR

Abstractions representing the eventual result of an async operation — a Promise or Future is a placeholder for a value not yet available, enabling non-blocking code composition without nested callbacks.

Explanation

A Promise (JavaScript term) or Future (Java/PHP term) represents a computation that may not have completed yet. The object provides methods to attach callbacks that run when the value is ready (then/onFulfilled) or when an error occurs (catch/onRejected). Promises solve callback hell — the pyramid of nested callbacks that becomes unreadable when composing multiple async operations. In JavaScript, Promises are built-in and async/await is syntactic sugar over them. In PHP, Promises appear in ReactPHP and Guzzle — Guzzle's async HTTP client returns PromiseInterface objects that can be composed with Utils::all() for parallel requests. PHP Fibers (8.1+) provide a lower-level cooperative multitasking primitive that async frameworks use internally. The key distinction: a Promise represents a result that will be ready; a Future is a handle to cancel or check the status of the operation as well.

Common Misconception

✗ PHP Promises provide true parallel execution. PHP is single-threaded — Promises and Fibers in PHP provide cooperative concurrency (one thing runs at a time, yielding control voluntarily) not parallel execution. Multiple Guzzle async requests run concurrently because they yield during network I/O wait time, not because PHP spawns threads. For CPU-bound parallelism in PHP, pcntl_fork(), separate processes, or a queue with multiple workers are the correct tools.

Why It Matters

Promises enable concurrent I/O without threads. A PHP script that needs to make five API calls can fire all five simultaneously with Guzzle's async client and Promise::all(), completing in the time of the slowest call rather than the sum of all five. Without Promises, sequential synchronous calls take 5× longer. For PHP applications with multiple external service dependencies — payment gateways, shipping APIs, product feeds — async Promises with concurrent requests is the highest-impact performance optimisation for integration-heavy pages.

Common Mistakes

Forgetting to call $pool->promise()->wait() — creating async Guzzle requests without waiting for them means they never execute.
Assuming PHP Promises provide thread-level parallelism — they provide I/O concurrency, not CPU parallelism.
Not handling Promise rejections — an unhandled rejection silently swallows errors in some implementations; always attach a catch handler.
Mixing synchronous and async code without understanding when execution occurs — a Promise callback runs when the event loop processes it, not immediately.

Code Examples

✗ Vulnerable

// Sequential — total time = sum of all request times
$client = new GuzzleHttp\Client();
$user    = $client->get('/api/user/' . $id)->getBody();    // 200ms
$orders  = $client->get('/api/orders?user=' . $id)->getBody(); // 180ms
$prefs   = $client->get('/api/prefs/' . $id)->getBody();   // 150ms
// Total: ~530ms

✓ Fixed

// Concurrent — total time = slowest single request
use GuzzleHttp\Client;
use GuzzleHttp\Utils;

$client  = new Client();
$promises = [
    'user'   => $client->getAsync('/api/user/' . $id),
    'orders' => $client->getAsync('/api/orders?user=' . $id),
    'prefs'  => $client->getAsync('/api/prefs/' . $id),
];

$results = Utils::unwrap(Utils::all($promises));
// All three fire simultaneously — total: ~200ms
$user   = json_decode($results['user']->getBody(), true);
$orders = json_decode($results['orders']->getBody(), true);

References

↗ https://docs.guzzlephp.org/en/stable/quickstart.html#async-requests