NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist, #139 most downloaded on Packagist
A lightweight implementation of CommonJS Promises/A for PHP
Latest stable
v3.3.0
Last release 1 years ago
19 Aug 2025
Ships fairly regularly
a new release about every 8 months
Nearly every release is documented
notes for 30 of 30 stable releases
Nothing withdrawn
no release was ever pulled
14 years old
30 releases · first in 2012
Drag across the ruler to compare, or tap a release to open it.
Feature: Improve PHP 8.5+ support by avoiding deprecated switch case syntax. ( #264 by @theodorejb )
Feature: Improve PHP 8.5+ support by avoiding deprecated switch case syntax.
(#264 by @theodorejb)
Feature: Run tests on PHP 8.4 and update test environment.
(#271 by @clue)
Feature: Improve PHP 8.4+ support by avoiding implicitly nullable type declarations. ( #260 by @Ayesh )
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Feature: Full PHP 8.3 compatibility. ( #255 by @clue )
The new catch() and finally() methods replace the deprecated otherwise() and always() methods which continue to exist for BC reasons. The old Extended…
A major new feature release, see release announcement.
We'd like to emphasize that this component is production ready and battle-tested.
We plan to support all long-term support (LTS) releases for at least 24 months,
so you have a rock-solid foundation to build on top of.
The v3 release will be the way forward for this package. However, we will still
actively support v2 and v1 to provide a smooth upgrade path for those not yet
on the latest versions.
This update involves some major new features and a minor BC break over the
v2.0.0 release. We've tried hard to avoid BC breaks where possible and
minimize impact otherwise. We expect that most consumers of this package will be
affected by BC breaks, but updating should take no longer than a few minutes.
See below for more details:
BC break: PHP 8.1+ recommended, PHP 7.1+ required.
(#138 and #149 by @WyriHaximus)
Feature / BC break: The PromiseInterface now includes the functionality of the old and ExtendedPromiseInterface.CancellablePromiseInterface
Each promise now always includes the then(), catch(), finally() and cancel() methods.
The new catch() and finally() methods replace the deprecated and otherwise() methods which continue to exist for BC reasons.always()
The old and ExtendedPromiseInterface are no longer needed and have been removed as a consequence.CancellablePromiseInterface
(#75 by @jsor and #208 by @clue and @WyriHaximus)
// old (multiple interfaces may or may not be implemented)
assert($promise instanceof PromiseInterface);
assert(method_exists($promise, 'then'));
if ($promise instanceof ExtendedPromiseInterface) { assert(method_exists($promise, 'otherwise')); }
if ($promise instanceof ExtendedPromiseInterface) { assert(method_exists($promise, 'always')); }
if ($promise instanceof CancellablePromiseInterface) { assert(method_exists($promise, 'cancel')); }
// new (single PromiseInterface with all methods)
assert($promise instanceof PromiseInterface);
assert(method_exists($promise, 'then'));
assert(method_exists($promise, 'catch'));
assert(method_exists($promise, 'finally'));
assert(method_exists($promise, 'cancel'));Feature / BC break: Improve type safety of promises. Require mixed fulfillment value argument and Throwable (or Exception) as rejection reason.
Add PHPStan template types to ensure strict types for resolve(T $value): PromiseInterface<T> and reject(Throwable $reason): PromiseInterface<never>.
It is no longer possible to resolve a promise without a value (use null instead) or reject a promise without a reason (use Throwable instead).
(#93, #141 and #142 by @jsor, #138, #149 and #247 by @WyriHaximus and #213 and #246 by @clue)
// old (arguments used to be optional)
$promise = resolve();
$promise = reject();
// new (already supported before)
$promise = resolve(null);
$promise = reject(new RuntimeException());Feature / BC break: Report all unhandled rejections by default and remove method.done()
Add new set_rejection_handler() function to set the global rejection handler for unhandled promise rejections.
(#248, #249 and #224 by @clue)
// Unhandled promise rejection with RuntimeException: Unhandled in example.php:2
reject(new RuntimeException('Unhandled'));BC break: Remove all deprecated APIs and reduce API surface.
Remove , some(), map() functions, use reduce()any() and all() functions instead.
Remove internal and FulfilledPromise classes, use RejectedPromiseresolve() and reject() functions instead.
Remove legacy promise progress API (deprecated third argument to then() method) and deprecated class.LazyPromise
(#32 and #98 by @jsor and #164, #219 and #220 by @clue)
BC break: Make all classes final to encourage composition over inheritance.
(#80 by @jsor)
Feature / BC break: Require array (or iterable) type for all() + race() + any() functions and bring in line with ES6 specification.
These functions now require a single argument with a variable number of promises or values as input.
(#225 by @clue and #35 by @jsor)
Fix / BC break: Fix race() to return a forever pending promise when called with an empty array (or iterable) and bring in line with ES6 specification.
(#83 by @jsor and #225 by @clue)
Minor performance improvements by initializing Deferred in the constructor and avoiding call_user_func() calls.
(#151 by @WyriHaximus and #171 by @Kubo2)
Minor documentation improvements.
(#110 by @seregazhuk, #132 by @CharlotteDunois, #145 by @danielecr, #178 by @WyriHaximus, #189 by @SrDante, #212 by @clue, #214, #239 and #243 by @SimonFrings and #231 by @nhedger)
The following changes had to be ported to this release due to our branching
strategy, but also appeared in the 2.x branch:
Feature: Support union types and address deprecation of ReflectionType::getClass() (PHP 8+).
(#197 by @cdosoftei and @SimonFrings)
Feature: Support intersection types (PHP 8.1+).
(#209 by @bzikarsky)
Feature: Port all memory improvements from 2.x to 3.x.
(#150 by @clue and @WyriHaximus)
Fix: Fix checking whether cancellable promise is an object and avoid possible warning.
(#161 by @smscr)
Improve performance by prefixing all global functions calls with \ to skip the look up and resolve process and go straight to the global function.
(#134 by @WyriHaximus)
Improve test suite, update PHPUnit and PHP versions and add .gitattributes to exclude dev files from exports.
(#107 by @carusogabriel, #148 and #234 by @WyriHaximus, #153 by @reedy, #162, #230 and #240 by @clue, #173, #177, #185 and #199 by @SimonFrings, #193 by @woodongwong and #210 by @bzikarsky)
The following changes were originally planned for this release but later reverted
and are not part of the final release:
Add iterative callback queue handler to avoid recursion (later removed to improve Fiber support).
(#28, #82 and #86 by @jsor, #158 by @WyriHaximus and #229 and #238 by @clue)
Trigger an E_USER_ERROR instead of throwing an exception from done() (later removed entire done() method to globally report unhandled rejections).
(#97 by @jsor and #224 and #248 by @clue)
Add type declarations for some() (later removed entire some() function).
(#172 by @WyriHaximus and #219 by @clue)
This is a compatibility release to ensure a smooth upgrade path for those not yet on Promise v3. We encourage upgrading to the latest version when pos
Feature: Support Disjunctive Normal Form Types (DNF types) for PHP 8.2+. ( #237 by @nhedger )
Feature: Support union types and address deprecation of ReflectionType::getClass() (PHP 8+). ( #198 by @cdosoftei and @SimonFrings )
Feature: Support union types and address deprecation of ReflectionType::getClass() (PHP 8+).
(#198 by @cdosoftei and @SimonFrings)
$promise->otherwise(function (OverflowException|UnderflowException $e) {
echo 'Error: ' . $e->getMessage() . PHP_EOL;
});Feature: Support intersection types (PHP 8.1+).
(#195 by @bzikarsky)
$promise->otherwise(function (OverflowException&CacheException $e) {
echo 'Error: ' . $e->getMessage() . PHP_EOL;
});Improve test suite, use GitHub actions for continuous integration (CI),
update to PHPUnit 9, and add full core team to the license.
(#174, #183, #186, and #201 by @SimonFrings and #211 by @clue)
Mark FulfilledPromise , RejectedPromise and LazyPromise as deprecated for Promise v2 (and remove for Promise v3). ( #143 and #165 by @clue )
Mark FulfilledPromise, RejectedPromise and LazyPromise as deprecated for Promise v2 (and remove for Promise v3).
(#143 and #165 by @clue)
// deprecated
$fulfilled = new React\Promise\FulfilledPromise($value);
$rejected = new React\Promise\RejectedPromise($reason);
// recommended alternatives
$fulfilled = React\Promise\resolve($value);
$rejected = React\Promise\reject($reason);Fix: Fix checking whether cancellable promise is an object and avoid possible warning.
(#168 by @smscr and @jsor)
Improve documentation and add docblocks to functions and interfaces.
(#135 by @CharlotteDunois)
Add .gitattributes to exclude dev files from exports.
(#154 by @reedy)
Improve test suite, run tests on PHP 7.4 and update PHPUnit test setup.
(#163 by @clue)
Fix: file_exists warning when resolving with long strings. ( #130 by @sbesselsen )
Feature: Improve memory consumption for pending promises by using static internal callbacks without binding to self. (#124 by @clue)
Mark legacy progress support / notification API as deprecated (#112 by @clue)
Feature: Significantly improve memory consumption and performance by only passing resolver args to resolver and canceller if callback requires them. Also use static callbacks without binding to promise, clean up canceller function reference when they are no longer needed and hide resolver and canceller references from call stack on PHP 7+. (#113, #115, #116, #117, #118, #119 and #123 by @clue)
These changes combined mean that rejecting promises with an Exception should
no longer cause any internal circular references which could cause some unexpected
memory growth in previous versions. By explicitly avoiding and explicitly
cleaning up said references, we can avoid relying on PHP's circular garbage collector
to kick in which significantly improves performance when rejecting many promises.
Mark legacy progress support / notification API as deprecated (#112 by @clue)
Recommend rejecting promises by throwing an exception (#114 by @jsor)
Improve documentation to properly instantiate LazyPromise (#121 by @holtkamp)
Follower cancellation propagation was originally planned for this release but has been reverted for now and is planned for a future release. (#99 by @jsor and #122 by @clue)
Fix circular references when resolving with a promise which follows itself (#94).
This was introduced in 42d86b7 (PR #36, released in v2.3.0) and was both unintended and backward incompatible.
Revert automatic cancellation of pending collection promises once the output promise resolves. This was introduced in 42d86b7 (PR #36, released in v2.3.0) and was both unintended and backward incompatible.
If you need automatic cancellation, you can use something like:
function allAndCancel(array $promises)
{
return \React\Promise\all($promises)
->always(function() use ($promises) {
foreach ($promises as $promise) {
if ($promise instanceof \React\Promise\CancellablePromiseInterface) {
$promise->cancel();
}
}
});
}
all() and map() functions now preserve the order of the array (#77).
Fix circular references when resolving a promise with itself (#71).
Fix some() not cancelling pending promises when too much input promises reject (16ff799).
some() not cancelling pending promises when too much input promises reject (16ff799).Support foreign thenables in resolve(). Any object that provides a then() method is now assimilated to a trusted promise that follows the state of thi
resolve().
Any object that provides a then() method is now assimilated to a trusted promise that follows the state of this thenable (#52).some() and any() for input arrays containing not enough items (#34).Allow cancellation of promises returned by functions working on promise collections (#36).
\Throwable in the same way as \Exception (#51 by @joshdifabio).Fix cancellation handlers called multiple times (#47 by @clue).
Fix stack error when resolving a promise in its own fulfillment or rejection handlers.
This release introduces the ExtendedPromiseInterface.
This release introduces the ExtendedPromiseInterface.
The ExtendedPromiseInterface extends the PromiseInterface with useful shortcut and utility methods which are not part of the Promises/A specification.
Introduce new CancellablePromiseInterface implemented by all promises.
Introduce new CancellablePromiseInterface implemented by all promises.
New major release. The goal was to streamline the API and to make it more compliant with other promise libraries and especially with the new upcoming
New major release. The goal was to streamline the API and to make it more compliant with other promise libraries and especially with the new upcoming ES6 promises specification.
This is a compatibility release to ensure a smooth upgrade path for those not yet on Promise v3. We encourage upgrading to the latest version when pos
This is a compatibility release to ensure a smooth upgrade path for those not
yet on Promise v3. We encourage upgrading to the latest version when possible,
as Promise v3 will be the way forward for this project.
Fix DeferredPromise to also implement the CancellablePromiseInterface.
DeferredPromise to also implement the CancellablePromiseInterface.This release makes the API more compatible with 2.0 while preserving full backward compatibility.
This release makes the API more compatible with 2.0 while preserving full backward compatibility.
This release makes the API more compatible with 2.0 while preserving full backward compatibility.
This release makes the API more compatible with 2.0 while preserving full backward compatibility.
React\Promise\Promise class.React\Promise\When and React\Promise\Util to functions while keeping the classes as a proxy for BC.Trigger PHP errors when invalid callback is passed.
When::lazy() to create lazy promises which will be initialized once a consumer calls the then() method.Add PromisorInterface for objects that have a promise() method.
PromisorInterface for objects that have a promise() method.Fix bug in When::any() not correctly unwrapping to a single result value
When::any() not correctly unwrapping to a single result value$promiseOrValue argument of When::resolve() and When::reject() is now optionalPrevent deep recursion which was reaching xdebug.max_nesting_level default of 100
See `1.x` CHANGELOG for more details.
See 1.x CHANGELOG for more details.
One column per quarter.