reactphp/promise: the Deferred keeps the resolver, the Promise is what you hand out
Promises/A implementation for PHP.
At a glance
- What is it?
- reactphp/promise implements CommonJS Promises/A for PHP by splitting authority from result. Its own page documents two of the three finally() cases and stops inside the third.
- Who is it for?
- This package fits PHP code that already reasons about asynchronous results and wants a small dependency with a narrow surface: two classes, five chained methods and a handful of free functions. What you get for that is a settled promise that never mutates and handlers the library promises to call at most once, which is the property event loop code actually depends on.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- reactphp/promise2,461 ★ · +0
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| reactphp/promise | 2.5k | 2.5k |
0 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A Deferred holds the authority, the Promise is the copy you hand out
Two objects carry this package, and the split between them is a split in authority rather than a copy of data. A Deferred represents a computation or unit of work that may not have completed yet, something that executes asynchronously and finishes at some point in the future. A Promise represents the result of that computation, so every deferred owns one promise acting as a placeholder for the value or the error it will eventually hold. Handing out that placeholder is the point of the design:
$deferred = new React\Promise\Deferred();
$promise = $deferred->promise();
$deferred->resolve(mixed $value);
$deferred->reject(\Throwable $reason);promise() returns the object you pass to consumers, while resolve() and reject() stay on the deferred you kept. resolve() takes a mixed value, and when that value is itself a promise the outer promise transitions to the state of the inner one once it is resolved, so a chained result settles through rather than nesting. reject() takes a \Throwable, which makes the failure reason an exception object rather than a string or a status code. The Deferred constructor accepts an optional $canceller argument and refers readers to the Promise section for what that argument does.
then() hands back a second promise and promises only one call
then() is the method carrying the real load, and its signature states the cost up front:
$transformedPromise = $promise->then(callable $onFulfilled = null, callable $onRejected = null);Both parameters are optional, and the call returns a new promise rather than mutating the one you invoked it on. That new promise fulfills with the return value of whichever handler ran, or rejects with whatever exception that handler threw. Two guarantees are stated for the pair registered in a single call: only one of $onFulfilled or $onRejected is ever called, never both, and neither is called more than once. Immutability is the other half of the contract. Once a promise is fulfilled or rejected it becomes immutable, and neither its state nor its result can be modified. So a deferred resolved twice has no second effect, and a chain of then() calls produces a tree of separate promises rather than one object mutating under every consumer attached to it.
catch() narrows by type hint, and the example stacks narrowest first
catch() is defined as a shortcut for `$promise->then(null, $onRejected);`, which matters less for the syntax than for the fact that it occupies the same handler slot and returns a promise you can keep chaining. The more useful detail is that the reason argument can be type hinted, so a chain can catch one exception class and let the rest travel onward:
$promise
->catch(function (\RuntimeException $reason) {
// Only catch \RuntimeException instances
// All other types of errors will propagate automatically
})
->catch(function (\Throwable $reason) {
// Catch other errors
});The example orders the pair narrowest first, a \RuntimeException handler, then a \Throwable fallback for whatever is left, and each callback receives the reason as its first argument. This is the one place in the package where PHP's own type system does part of the error routing work, and it means the position of a catch in the chain is as load bearing as its argument type.
finally() states two cases and the third one stops mid-sentence
The cleanup hook is where the page runs out. finally() takes a single callable and arranges for it to be called with no arguments whether the promise fulfills or rejects, returning a new promise rather than reusing the old one. Two of the cases are written out in full: if $promise fulfills and $onFulfilledOrRejected returns successfully, the new promise fulfills with the same value as the original; if $promise fulfills and the callback throws or hands back a rejected promise, the new promise rejects with the thrown exception or with that rejected promise's reason. The third case starts, if $promise rejects and the callback returns successfully then $newPromise will reject with the same reason as, and the line stops on the variable name it was about to print. So the documented behaviour for cleanup on the rejection path, the case where a callback that swallows the exception should leave the chain rejecting and hand the reason along, is announced in the bullet list and never finished on the page.
otherwise() and always() sit struck-through while six free functions are only named
Two entries in the table of contents are struck through: PromiseInterface::otherwise() and PromiseInterface::always(). They are listed rather than deleted, and they sit inside the same PromiseInterface block as then(), catch(), finally() and cancel(), so the interface documented on this page has four live methods and two retired names. Retiring otherwise() follows from the text itself, because catch() is already defined as a shortcut for then(null, $onRejected) and covers that slot. Below the interface, the contents list names six free functions: resolve(), reject(), all(), race(), any() and set_rejection_handler(). Only two of them are reachable from the sections that are present, because Deferred::resolve() and Deferred::reject() each close with a cross-reference to the matching function. The bodies of all(), race(), any() and set_rejection_handler() are announced by the contents and not written out, which leaves the joining and mapping behaviour the introduction promises, joining multiple promises and mapping and reducing collections of promises, without its API on the page.
Two PHPUnit config files and one phpstan file at the root
The repository root has twelve entries and none of them is a documentation site. The test configuration is duplicated: phpunit.xml.dist and phpunit.xml.legacy sit side by side, which is the shape a library takes when it runs its suite against two PHPUnit configuration schemas. Static analysis has a file of its own, phpstan.neon.dist, the implementation lives in src/ and the suite in tests/. composer.json sits beside LICENSE and CHANGELOG.md, with .gitattributes and .gitignore at the same level and .github/ holding the workflow side, matching the Actions badge at the top of the page. The contents list also promises four closing sections, Install, Tests, Credits and License, and none of them has a body after the finally() rules. The install path and the command that runs the suite are named as headings only, and composer.json appears in the tree without its contents being spelled out anywhere on the page, which leaves the PHP version floor and the require line to be found elsewhere.
v3.3.0 shipped in August 2025 and the 3.x branch moved on afterwards
The release dates show where the project sits. The three most recent tags are v3.1.0 on 2023-11-16, v3.2.0 on 2024-05-24 and v3.3.0 on 2025-08-19, so the two gaps run about eighteen months and then about fifteen. The default branch is 3.x and it received a push on 2026-05-10, months after the v3.3.0 tag, so work has landed on that branch which no release has picked up yet. The repository is not archived, the license is MIT, the primary language is PHP, and it lists 2461 stars, 149 forks and 0 open issues. The project names reactphp.org/promise/ as its home and points at the CommonJS Promises/A wiki page as the specification it targets, and anyone who has never met a promise before is sent to a separate primer gist rather than being walked through the concept on this page.
Editorial conclusion
This package fits PHP code that already reasons about asynchronous results and wants a small dependency with a narrow surface: two classes, five chained methods and a handful of free functions. What you get for that is a settled promise that never mutates and handlers the library promises to call at most once, which is the property event loop code actually depends on. What you cannot get from the project page is the part that would decide an adoption: no PHP version floor is stated, no install command is written out, and the rejection branch of finally() ends mid-sentence. Read composer.json and the remaining half of that bullet list before you commit a codebase to it.
Frequently asked questions
What does reactphp/promise add to PHP?
It is a MIT licensed PHP implementation of the CommonJS Promises/A proposal, built around a Deferred that keeps the resolve and reject authority and a Promise object that gets handed to consumers, plus free functions for resolving, rejecting, joining and racing.
What does reactphp/promise guarantee about handlers passed to then()?
For handlers registered in one call to then(), only one of $onFulfilled or $onRejected is ever called and never both, and neither handler is called more than once. A settled promise also becomes immutable, so its state and its result cannot be modified afterwards.
Does reactphp/promise still have otherwise() and always()?
Both names appear in the table of contents with strikethrough formatting, in the same PromiseInterface block as then(), catch(), finally() and cancel(). catch() is already defined as a shortcut for then(null, $onRejected), so it covers the ground otherwise() would have taken.
How do I catch only one exception type with reactphp/promise?
Type hint the reason argument of the callback you pass to catch(). The worked example registers a handler for \RuntimeException first and a second handler for \Throwable after it, so the specific case is matched before the general fallback.
What PHP version does reactphp/promise require?
The project page does not state one. A composer.json sits at the root of the repository and the package page is linked from the header, so the version floor has to be checked there instead of assumed from the release tags.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/reactphp-promise)Star history chart for your README
[](https://hysenlabs.com/projects/reactphp-promise)Was this useful?