Download the PHP package moebius/promise without Composer
On this page you can find all versions of the php package moebius/promise. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download moebius/promise
More information about moebius/promise
Files in moebius/promise
Package promise
Short Description A flexible and compatible promise implementation for PHP.
License MIT
Informations about the package promise
moebius/promise
A pure Promises/A+ promise implementation, designed to be flexible and well tested - and promoting interoperability.
Promise interface
Promise objects have the following clean interface. This interface and implementation follows the ECMAScript Promise Specification as closely as possible. This means that you you can assume that the same semantics you know from javascript will work for these promises.
Interoperability
It is very common for promise-aware PHP libraries to explicitly type-check objects for compatability. This library provides a type-checking functions for this purpose:
Type casting
If you need to ensure that the provided object follows the Promises/A+ semantics, with
chainable then()
- you should use the Moebius\Promise::cast()
method:
Type checking
// Type casting $promise = Promise::cast($someObject);
Casting a promise
Promises from other implementations can be cast to Moebius\Promise.
Identifying a promise-like object
Since there is no canonical PHP promise interface, it is useful to have a simple way to check if an object appears to be a valid promise.
Creating a promise
Promises can generally be created in two ways; with a resolver function
or without a resolver function - in which case the promise must be resolved
by calling the fulfill()
or the reject()
method.
*With a resolver function**
Without a resolver function
Interoperability Notes
The interface is focused on the resolution of promises; it does not care about how a promise is created - the interface is for functions that accept a promise.
Most promise implementations have an extensive API, but a promise only needs
to expose a then()
function to be usable by 90% of libraries.
It is also very helpful to have a way to determine if a promise is already resolved or rejected - which generally is implemented using a method which returns a string "pending", "resolved", "rejected" or "fulfilled".
This library implements methods isPending()
, isResolved()
and isFulfilled()
because these methods can be implemented regardless of how the underlying
promise implementation records that state..
Many promise implementations have methods like otherwise()
, finally()
and
similar - which may be convenient, but it reduces interoperability because
the same features can be implemented in several ways and with different names.
A promise implementation which is widely compatible with various libraries.
Modelled after the Promises/A+ specification in JavaScript.
If you create a Moebius\Promise
instance, it is directly usable as a drop-in
replacement for:
guzzlehttp/promises
by implementingGuzzleHttp\Promise\PromiseInterface
react/promise
by implementingReact\Promise\PromiseInterface
- 'php-http/promise' by implementing
Http\Promise\Promise
amphp/amp
by implementingAmp\Promise
The Moebius\Promise
objects have two primary uses: As a standard Promise
object, and as a Deferred
object using React terminology.
Basic Promise Usage
This is the most common way to use a promise:
"Deferred" usage
In React and some other libraries, an additional type of promise is called a "deferred" promise. Moebius combines these two uses:
Supporting other promises yourself
To support other promise implementations yourself, the convention
has been to use reflection to inspect the then()
method.
Moebius Promise provides two ways to support other promises and ensure a consistent usage:
Casting
Implementation details
In order to maintain compatability both Guzzle and PhpHttp promises, we
have made some "trickery". It turns out that PhpHttp-promises are modelled
after Guzzle promises, and are in fact compatible. Guzzle promises are
a superset of PhpHttp promises, so if PhpHttp is installed - it will be
class_alias()
'ed to replace the GuzzleHttp\Promise\PromiseInterface
.
These constants now live in the Moebius\Promise\SuperPromiseInterface
class,
so that they are available in both child classes while not being ambiguous
according to PHP.
Promise resolution
Guzzle is quite particular when it comes to promise resolution, in that it will defer running the resolve function until you actually request the value. This is not ideal for an event loop implementation - because, for example if your task takes 1 second to run - you would want to start running that task as soon as possible. This is not noticeable when only using it with Guzzle, but when combined with other async tasks it becomes annoying.
We don't expect this to be a problem.
Promise::wait()
Guzzle and PhpHttp implements a wait()
function, which is intended to
start running the asynchronous jobs - almost like using the promise tree
as an event-loop.
Basic usage
Normally you will pass a resolve function into the promise when it is constructed. This variant is the most common way to use promises.
Deferred usage
In some cases, you are unable to resolve the promise from inside the promise. This way you can hold on to a reference of the promise and resolve (or reject) it after you return it.
Note: While is possible to call the resolve/reject methods multiple times, only the first call has an effect.
API documentation
Handling multiple promises efficiently:
-
Promise::all(iterable $promises): Promise
. If all promises are resolved, the returned promise will resolve with an array of all the promises. If any of the promises are rejected, the returned promise is also rejected. -
Promise::allSettled(iterable $promises): Promise
. Once all the promise have a result, the returned promise is resolved with an array of the promises. -
Promise::any(iterable $promises): Promise
. If any of the promises are resolved, the returned promise is resolved with the first value. If all promises are rejected, the returned promise is rejected. Promise::race(iterable $promises): Promise
. The first promise which is either resolved or rejected will be the result of the returned promise.
Interoperability with other promise implementations:
Promise::cast($promise): Promise
. Any object with a promise-like 'then' function is converted into a Moebius\Promise instance.
Subscribing to the result of a promise:
$promise->then(callable $onFulfilled=null, callable $onRejected=null): Promise
. The passed functions will be invoked immediately if the promise has already been settled (fulfilled or rejected). The returned promise is a new promise which will be resolved or rejected with the value from the callbacks.
Resolving a promise externally:
-
$promise->resolve($value)
. $promise->reject($reason)
.
All versions of promise with dependencies
charm/fallback-logger Version ^1.0
moebius/common Version ^1.0
charm/util-closuretool Version ^1.0