Promise
A lightweight implementation of CommonJS Promises/A for PHP.
Table of Contents
- Introduction
- Concepts
- API
- Examples
- Install
- Credits
- License
Introduction
Promise is a library implementing CommonJS Promises/A for PHP.
It also provides several other useful promise-related concepts, such as joining multiple promises and mapping and reducing collections of promises.
If you've never heard about promises before, read this first.
Concepts
Deferred
A Deferred represents a computation or unit of work that may not have completed yet. Typically (but not always), that computation will be something that executes asynchronously and completes at some point in the future.
Promise
While a deferred represents the computation itself, a Promise represents the result of that computation. Thus, each deferred has a promise that acts as a placeholder for its actual result.
API
Deferred
A deferred represents an operation whose resolution is pending. It has separate promise and resolver parts.
$deferred = new React\Promise\Deferred();
$promise = $deferred->promise();
$deferred->resolve(mixed $value = null);
$deferred->reject(mixed $reason = null);
$deferred->notify(mixed $update = null);
The promise
method returns the promise of the deferred.
The resolve
and reject
methods control the state of the deferred.
The deprecated notify
method is for progress notification.
The constructor of the Deferred
accepts an optional $canceller
argument.
See Promise for more information.
Deferred::promise()
$promise = $deferred->promise();
Returns the promise of the deferred, which you can hand out to others while keeping the authority to modify its state to yourself.
Deferred::resolve()
$deferred->resolve(mixed $value = null);
Resolves the promise returned by promise()
. All consumers are notified by
having $onFulfilled
(which they registered via $promise->then()
) called with
$value
.
If $value
itself is a promise, the promise will transition to the state of
this promise once it is resolved.
Deferred::reject()
$deferred->reject(mixed $reason = null);
Rejects the promise returned by promise()
, signalling that the deferred's
computation failed.
All consumers are notified by having $onRejected
(which they registered via
$promise->then()
) called with $reason
.
If $reason
itself is a promise, the promise will be rejected with the outcome
of this promise regardless whether it fulfills or rejects.
Deferred::notify()
Deprecated in v2.6.0: Progress support is deprecated and should not be used anymore.
$deferred->notify(mixed $update = null);
Triggers progress notifications, to indicate to consumers that the computation is making progress toward its result.
All consumers are notified by having $onProgress
(which they registered via
$promise->then()
) called with $update
.
PromiseInterface
The promise interface provides the common interface for all promise implementations.
A promise represents an eventual outcome, which is either fulfillment (success) and an associated value, or rejection (failure) and an associated reason.
Once in the fulfilled or rejected state, a promise becomes immutable. Neither its state nor its result (or error) can be modified.
Implementations
- Promise
- FulfilledPromise (deprecated)
- RejectedPromise (deprecated)
- LazyPromise (deprecated)
PromiseInterface::then()
$transformedPromise = $promise->then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
Transforms a promise's value by applying a function to the promise's fulfillment or rejection value. Returns a new promise for the transformed result.
The then()
method registers new fulfilled, rejection and progress handlers
with a promise (all parameters are optional):
$onFulfilled
will be invoked once the promise is fulfilled and passed the result as the first argument.$onRejected
will be invoked once the promise is rejected and passed the reason as the first argument.$onProgress
(deprecated) will be invoked whenever the producer of the promise triggers progress notifications and passed a single argument (whatever it wants) to indicate progress.
It returns a new promise that will fulfill with the return value of either
$onFulfilled
or $onRejected
, whichever is called, or will reject with
the thrown exception if either throws.
A promise makes the following guarantees about handlers registered in
the same call to then()
:
- Only one of
$onFulfilled
or$onRejected
will be called, never both. $onFulfilled
and$onRejected
will never be called more than once.$onProgress
(deprecated) may be called multiple times.
See also
- resolve() - Creating a resolved promise
- reject() - Creating a rejected promise
- ExtendedPromiseInterface::done()
- done() vs. then()
ExtendedPromiseInterface
The ExtendedPromiseInterface extends the PromiseInterface with useful shortcut and utility methods which are not part of the Promises/A specification.
Implementations
- Promise
- FulfilledPromise (deprecated)
- RejectedPromise (deprecated)
- LazyPromise (deprecated)
ExtendedPromiseInterface::done()
$promise->done(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
Consumes the promise's ult