Promise
in package
An implementation of the Promise pattern.
A promise represents the result of an asynchronous operation. At any given point a promise can be in one of three states:
- Pending (the promise does not have a result yet).
- Fulfilled (the asynchronous operation has completed with a result).
- Rejected (the asynchronous operation has completed with an error).
To get a callback when the operation has finished, use the then method.
Tags
Table of Contents
- FULFILLED = 1
- The asynchronous operation has completed, and has a result.
- PENDING = 0
- The asynchronous operation is pending.
- REJECTED = 2
- The asynchronous operation has completed with an error.
- $state : int
- The current state of this promise.
- $subscribers : array<string|int, mixed>
- A list of subscribers. Subscribers are the callbacks that want us to let them know if the callback was fulfilled or rejected.
- $value : mixed
- The result of the promise.
- __construct() : mixed
- Creates the promise.
- fulfill() : mixed
- Marks this promise as fulfilled and sets its return value.
- otherwise() : Promise
- Add a callback for when this promise is rejected.
- reject() : mixed
- Marks this promise as rejected, and set it's rejection reason.
- then() : Promise
- This method allows you to specify the callback that will be called after the promise has been fulfilled or rejected.
- wait() : mixed
- Stops execution until this promise is resolved.
- invokeCallback() : mixed
- This method is used to call either an onFulfilled or onRejected callback.
Constants
FULFILLED
The asynchronous operation has completed, and has a result.
public
mixed
FULFILLED
= 1
PENDING
The asynchronous operation is pending.
public
mixed
PENDING
= 0
REJECTED
The asynchronous operation has completed with an error.
public
mixed
REJECTED
= 2
Properties
$state
The current state of this promise.
public
int
$state
= self::PENDING
$subscribers
A list of subscribers. Subscribers are the callbacks that want us to let them know if the callback was fulfilled or rejected.
protected
array<string|int, mixed>
$subscribers
= []
$value
The result of the promise.
protected
mixed
$value
= null
If the promise was fulfilled, this will be the result value. If the promise was rejected, this property hold the rejection reason.
Methods
__construct()
Creates the promise.
public
__construct([callable $executor = null ]) : mixed
The passed argument is the executor. The executor is automatically called with two arguments.
Each are callbacks that map to $this->fulfill and $this->reject. Using the executor is optional.
Parameters
- $executor : callable = null
Return values
mixed —fulfill()
Marks this promise as fulfilled and sets its return value.
public
fulfill([mixed $value = null ]) : mixed
Parameters
- $value : mixed = null
Return values
mixed —otherwise()
Add a callback for when this promise is rejected.
public
otherwise(callable $onRejected) : Promise
Its usage is identical to then(). However, the otherwise() function is preferred.
Parameters
- $onRejected : callable
Return values
Promise —reject()
Marks this promise as rejected, and set it's rejection reason.
public
reject(Throwable $reason) : mixed
Parameters
- $reason : Throwable
Return values
mixed —then()
This method allows you to specify the callback that will be called after the promise has been fulfilled or rejected.
public
then([callable $onFulfilled = null ][, callable $onRejected = null ]) : Promise
Both arguments are optional.
This method returns a new promise, which can be used for chaining. If either the onFulfilled or onRejected callback is called, you may return a result from this callback.
If the result of this callback is yet another promise, the result of that promise will be used to set the result of the returned promise.
If either of the callbacks return any other value, the returned promise is automatically fulfilled with that value.
If either of the callbacks throw an exception, the returned promise will be rejected and the exception will be passed back.
Parameters
- $onFulfilled : callable = null
- $onRejected : callable = null
Return values
Promise —wait()
Stops execution until this promise is resolved.
public
wait() : mixed
This method stops execution completely. If the promise is successful with a value, this method will return this value. If the promise was rejected, this method will throw an exception.
This effectively turns the asynchronous operation into a synchronous one. In PHP it might be useful to call this on the last promise in a chain.
Return values
mixed —invokeCallback()
This method is used to call either an onFulfilled or onRejected callback.
private
invokeCallback(Promise $subPromise[, callable $callBack = null ]) : mixed
This method makes sure that the result of these callbacks are handled correctly, and any chained promises are also correctly fulfilled or rejected.
Parameters
- $subPromise : Promise
- $callBack : callable = null