A lightweight, strongly typed promise library for PHP 8.4. Built for performance, with no dependencies or event loop required.
composer require trixnew/vowCreate a Deferred to resolve or reject a promise, and use observe() to handle the result.
use Vow\Deferred;
$deferred = new Deferred();
$deferred->promise->observe(
fn (string $body) => print "got $body\n",
fn (Throwable $e) => print "failed: {$e->getMessage()}\n",
);
$deferred->resolve('hello');
// or $deferred->reject(new RuntimeException('boom'));Keep the Deferred where the operation is handled and pass its promise to consumers. Promises are read-only, so they can't be resolved or rejected from the outside.
Use then(), catch(), and finally() to chain operations. If a callback returns another promise, Vow automatically adopts its result.
$user = fetchUser($id)
->then(fn (array $row) => fetchProfile($row['id']))
->then(fn (array $profile) => $profile['name'])
->catch(fn (Throwable $e) => 'anonymous')
->finally(fn () => $log->debug('done'));$promise->isPending();
$promise->isFulfilled();
$promise->isRejected();
$promise->value(); // Returns the value or throws
$promise->reason(); // Returns the rejection reason or nullCalling value() on a pending promise throws a LogicException. Rejected promises throw their rejection reason.
use Vow\Promise;
$ok = Promise::resolved(42);
$no = Promise::rejected(new RuntimeException('nope'));Vow includes the usual promise combinators, with array keys preserved.
Promise::all(['a' => $a, 'b' => $b]); // All values, or the first rejection
Promise::allSettled([$a, $b]); // Wait for every result
Promise::race([$a, $b]); // First to settle
Promise::any([$a, $b]); // First to fulfillIf every promise passed to any() rejects, the result is an AggregateException containing the individual reasons in $reasons.
Cancelled promises ignore late results, making it safe for an operation to finish after a timeout.
$deferred = new Deferred();
$deferred->cancel(); // Rejects with CancelledException
$deferred->resolve('late'); // IgnoredUnhandled rejections are written to error_log() by default. You can provide your own handler:
Promise::setRejectionHandler(
fn (Throwable $e) => $logger->error(
$e->getMessage(),
['exception' => $e],
),
);Vow supports PHP fibers through Promise::async() and await(), allowing asynchronous-looking code without callbacks at every step.
$result = Promise::async(function () use ($client) {
$user = $client->fetchUser(1)->await();
$posts = $client->fetchPosts($user['id'])->await();
return count($posts);
});async() runs the function in a fiber, while await() suspends it until the promise settles.
Calling await() on a pending promise outside Promise::async() throws a LogicException.
Vow keeps promise execution predictable:
- Synchronous callbacks. Handlers run immediately when a promise settles, or when attached to an already settled promise.
- Consistent ordering. Callbacks execute in the order they were registered.
- Stack-safe chains. Derived promises settle after their parent's callbacks, avoiding stack growth in long chains.
- Single settlement. Promises can only settle once. Repeated calls throw a
LogicException, except after cancellation. - Callback isolation. If an
observe()callback throws, the remaining callbacks still run. The first exception is then rethrown. - Unhandled rejections. Rejections are reported when the promise is released. Cancellations are excluded.
- Thread ownership. Promises aren't thread-safe and must be settled on their owning thread.
Benchmarked on PHP 8.4 using the median of interleaved runs in fresh processes. Results are measured in nanoseconds per operation (lower is better).
| Scenario | Vow | ReactPHP | Amp |
|---|---|---|---|
| Create + resolve | 285 | 1,134 | 451 |
| Pending, 1 handler | 709 | 3,282 | 9,227 |
| Settled, 1 handler | 402 | 1,599 | 9,413 |
| Chain of 10 | 6,867 | 24,326 | 36,752 |
| all() of 10 | 10,740 | 42,261 | – |
| Scenario | Vow | ReactPHP | Amp |
|---|---|---|---|
| Create + resolve | 159 | 789 | 317 |
| Pending, 1 handler | 348 | 2,435 | 8,163 |
| Settled, 1 handler | 203 | 1,040 | 8,089 |
| Chain of 10 | 3,976 | 18,442 | 32,007 |
| all() of 10 | 6,099 | 30,607 | – |
Bytes per pending promise with one handler (lower is better).
| Vow | ReactPHP | Amp |
|---|---|---|
| 409 | 4,728 | 3,184 |
Vow performs well across the benchmarks, particularly with JIT enabled, where it leads in every tested scenario.
See tests/bench/RESULTS.md for the full results and methodology.
To run the benchmarks yourself:
cd tests/bench
composer install
php run.phpcomposer install
composer test
composer analyse