Sabre\Event\Promise Class Reference

An implementation of the Promise pattern. More...

Collaboration diagram for Sabre\Event\Promise:

Data Structures
class	FunctionsTest
class	PromiseTest

Public Member Functions
	__construct (callable $executor=null)
	Creates the promise. More...
	then (callable $onFulfilled=null, callable $onRejected=null)
	This method allows you to specify the callback that will be called after the promise has been fulfilled or rejected. More...
	otherwise (callable $onRejected)
	Add a callback for when this promise is rejected. More...
	fulfill ($value=null)
	Marks this promise as fulfilled and sets its return value. More...
	reject ($reason=null)
	Marks this promise as rejected, and set it's rejection reason. More...
	wait ()
	Stops execution until this promise is resolved. More...
	error (callable $onRejected)
	Alias for 'otherwise'. More...

Static Public Member Functions
static	all (array $promises)
	Deprecated. More...

Data Fields
const	PENDING = 0
	The asynchronous operation is pending. More...
const	FULFILLED = 1
	The asynchronous operation has completed, and has a result. More...
const	REJECTED = 2
	The asynchronous operation has completed with an error. More...
	$state = self::PENDING

Protected Attributes
	$subscribers = []
	$value = null

Private Member Functions
	invokeCallback (Promise $subPromise, callable $callBack=null)
	This method is used to call either an onFulfilled or onRejected callback. More...

Detailed Description

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:

1. Pending (the promise does not have a result yet).
2. Fulfilled (the asynchronous operation has completed with a result).
3. Rejected (the asynchronous operation has completed with an error).

To get a callback when the operation has finished, use the then method.

Copyright

Copyright (C) 2013-2015 fruux GmbH (https://fruux.com/).

Author

Evert Pot (http://evertpot.com/) http://sabre.io/license/ Modified BSD License

Definition at line 23 of file Promise.php.

Constructor & Destructor Documentation

__construct()

Sabre\Event\Promise::__construct

(

callable

$executor = null

)

Creates the promise.

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

callable

$executor

Definition at line 58 of file Promise.php.

                                                    {

        if ($executor) {
            $executor(
                [$this, 'fulfill'],
                [$this, 'reject']
            );
        }

    }

Member Function Documentation

all()

static Sabre\Event\Promise::all ( array  $promises )

static

Deprecated.

Please use Sabreall

Parameters

Promise[]

$promises

Deprecated:

Returns

Promise

Definition at line 314 of file Promise.php.

Referenced by Sabre\Event\Promise\FunctionsTest\testAll(), Sabre\Event\PromiseTest\testAll(), Sabre\Event\Promise\PromiseTest\testAll(), Sabre\Event\Promise\FunctionsTest\testAllReject(), Sabre\Event\PromiseTest\testAllReject(), Sabre\Event\Promise\PromiseTest\testAllReject(), Sabre\Event\Promise\FunctionsTest\testAllRejectThenResolve(), Sabre\Event\PromiseTest\testAllRejectThenResolve(), and Sabre\Event\Promise\PromiseTest\testAllRejectThenResolve().

                                         {

        return Promise\all($promises);

    }

Here is the caller graph for this function:

error()

Sabre\Event\Promise::error

(

callable

$onRejected

)

Alias for 'otherwise'.

This function is now deprecated and will be removed in a future version.

Parameters

callable

$onRejected

Deprecated:

Returns

Promise

Definition at line 299 of file Promise.php.

References Sabre\Event\Promise\otherwise().

Referenced by Sabre\Event\Promise\all().

                                         {

        return $this->otherwise($onRejected);

    }

Here is the call graph for this function:

Here is the caller graph for this function:

fulfill()

Sabre\Event\Promise::fulfill

(

$value = null

)

Marks this promise as fulfilled and sets its return value.

Parameters

mixed

$value

Returns

void

Definition at line 141 of file Promise.php.

References Sabre\Event\Promise\$value, and Sabre\Event\Promise\invokeCallback().

Referenced by Sabre\Event\Promise\invokeCallback().

                                    {
        if ($this->state !== self::PENDING) {
            throw new PromiseAlreadyResolvedException('This promise is already resolved, and you\'re not allowed to resolve a promise more than once');
        }
        $this->state = self::FULFILLED;
        $this->value = $value;
        foreach ($this->subscribers as $subscriber) {
            $this->invokeCallback($subscriber[0], $subscriber[1]);
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

invokeCallback()

Sabre\Event\Promise::invokeCallback ( Promise  $subPromise, callable  $callBack = null  )

private

This method is used to call either an onFulfilled or onRejected callback.

This method makes sure that the result of these callbacks are handled correctly, and any chained promises are also correctly fulfilled or rejected.

Parameters

Promise	$subPromise
callable	$callBack

Returns

void

Definition at line 252 of file Promise.php.

References $result, Sabre\Event\Promise\fulfill(), Sabre\Event\Loop\nextTick(), and Sabre\Event\Promise\reject().

Referenced by Sabre\Event\Promise\fulfill(), Sabre\Event\Promise\reject(), and Sabre\Event\Promise\then().

                                                                                    {

        // We use 'nextTick' to ensure that the event handlers are always
        // triggered outside of the calling stack in which they were originally
        // passed to 'then'.
        //
        // This makes the order of execution more predictable.
        Loop\nextTick(function() use ($callBack, $subPromise) {
            if (is_callable($callBack)) {
                try {

                    $result = $callBack($this->value);
                    if ($result instanceof self) {
                        // If the callback (onRejected or onFulfilled)
                        // returned a promise, we only fulfill or reject the
                        // chained promise once that promise has also been
                        // resolved.
                        $result->then([$subPromise, 'fulfill'], [$subPromise, 'reject']);
                    } else {
                        // If the callback returned any other value, we
                        // immediately fulfill the chained promise.
                        $subPromise->fulfill($result);
                    }
                } catch (Exception $e) {
                    // If the event handler threw an exception, we need to make sure that
                    // the chained promise is rejected as well.
                    $subPromise->reject($e);
                }
            } else {
                if ($this->state === self::FULFILLED) {
                    $subPromise->fulfill($this->value);
                } else {
                    $subPromise->reject($this->value);
                }
            }
        });
    }

Here is the call graph for this function:

Here is the caller graph for this function:

otherwise()

Sabre\Event\Promise::otherwise

(

callable

$onRejected

)

Add a callback for when this promise is rejected.

Its usage is identical to then(). However, the otherwise() function is preferred.

Parameters

callable

$onRejected

Returns

Promise

Definition at line 129 of file Promise.php.

References Sabre\Event\Promise\then().

Referenced by Sabre\Event\Promise\error().

                                             {

        return $this->then(null, $onRejected);

    }

Here is the call graph for this function:

Here is the caller graph for this function:

reject()

Sabre\Event\Promise::reject

(

$reason = null

)

Marks this promise as rejected, and set it's rejection reason.

While it's possible to use any PHP value as the reason, it's highly recommended to use an Exception for this.

Parameters

mixed

$reason

Returns

void

Definition at line 161 of file Promise.php.

References Sabre\Event\Promise\invokeCallback().

Referenced by Sabre\Event\Promise\invokeCallback(), and Sabre\Event\Promise\FunctionsTest\testReject().

                                    {
        if ($this->state !== self::PENDING) {
            throw new PromiseAlreadyResolvedException('This promise is already resolved, and you\'re not allowed to resolve a promise more than once');
        }
        $this->state = self::REJECTED;
        $this->value = $reason;
        foreach ($this->subscribers as $subscriber) {
            $this->invokeCallback($subscriber[0], $subscriber[2]);
        }

    }

Here is the call graph for this function:

Here is the caller graph for this function:

then()

Sabre\Event\Promise::then	(	callable	$onFulfilled = null,
		callable	$onRejected = null
	)

This method allows you to specify the callback that will be called after the promise has been fulfilled or rejected.

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

callable	$onFulfilled
callable	$onRejected

Returns

Promise

Definition at line 92 of file Promise.php.

References Sabre\Event\Promise\invokeCallback().

Referenced by Sabre\Event\Promise\otherwise(), Sabre\Event\Promise\PromiseTest\testChain(), Sabre\Event\Promise\PromiseTest\testChainPromise(), and Sabre\Event\Promise\PromiseTest\testFromFailureHandler().

                                                                             {

        // This new subPromise will be returned from this function, and will
        // be fulfilled with the result of the onFulfilled or onRejected event
        // handlers.
        $subPromise = new self();

        switch ($this->state) {
            case self::PENDING :
                // The operation is pending, so we keep a reference to the
                // event handlers so we can call them later.
                $this->subscribers[] = [$subPromise, $onFulfilled, $onRejected];
                break;
            case self::FULFILLED :
                // The async operation is already fulfilled, so we trigger the
                // onFulfilled callback asap.
                $this->invokeCallback($subPromise, $onFulfilled);
                break;
            case self::REJECTED :
                // The async operation failed, so we call teh onRejected
                // callback asap.
                $this->invokeCallback($subPromise, $onRejected);
                break;
        }
        return $subPromise;

    }

Here is the call graph for this function:

Here is the caller graph for this function:

wait()

Sabre\Event\Promise::wait

(

)

Stops execution until this promise is resolved.

This method stops exection 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.

Exceptions

Exception

Returns

mixed

Definition at line 187 of file Promise.php.

References $type, Sabre\Event\Promise\$value, and Sabre\Event\Loop\tick().

                    {

        $hasEvents = true;
        while ($this->state === self::PENDING) {

            if (!$hasEvents) {
                throw new \LogicException('There were no more events in the loop. This promise will never be fulfilled.');
            }

            // As long as the promise is not fulfilled, we tell the event loop
            // to handle events, and to block.
            $hasEvents = Loop\tick(true);

        }

        if ($this->state === self::FULFILLED) {
            // If the state of this promise is fulfilled, we can return the value.
            return $this->value;
        } else {
            // If we got here, it means that the asynchronous operation
            // errored. Therefore we need to throw an exception.
            $reason = $this->value;
            if ($reason instanceof Exception) {
                throw $reason;
            } elseif (is_scalar($reason)) {
                throw new Exception($reason);
            } else {
                $type = is_object($reason) ? get_class($reason) : gettype($reason);
                throw new Exception('Promise was rejected with reason of type: ' . $type);
            }
        }


    }

Here is the call graph for this function:

Field Documentation

$state

Sabre\Event\Promise::$state = self::PENDING

Definition at line 45 of file Promise.php.

$subscribers

Sabre\Event\Promise::$subscribers = []

protected

Definition at line 229 of file Promise.php.

$value

Sabre\Event\Promise::$value = null

protected

Definition at line 239 of file Promise.php.

Referenced by Sabre\Event\Promise\fulfill(), Sabre\Event\Promise\resolve(), Sabre\Event\Promise\FunctionsTest\testAll(), Sabre\Event\Promise\PromiseTest\testAll(), Sabre\Event\Promise\FunctionsTest\testAllReject(), Sabre\Event\Promise\PromiseTest\testAllReject(), Sabre\Event\Promise\FunctionsTest\testAllRejectThenResolve(), Sabre\Event\Promise\PromiseTest\testAllRejectThenResolve(), Sabre\Event\Promise\PromiseTest\testChain(), Sabre\Event\Promise\PromiseTest\testChainPromise(), Sabre\Event\Promise\PromiseTest\testFail(), Sabre\Event\Promise\PromiseTest\testPendingFail(), Sabre\Event\Promise\PromiseTest\testPendingResult(), Sabre\Event\Promise\FunctionsTest\testRace(), Sabre\Event\Promise\FunctionsTest\testRaceReject(), Sabre\Event\Promise\FunctionsTest\testReject(), Sabre\Event\Promise\FunctionsTest\testResolve(), Sabre\Event\Promise\PromiseTest\testSuccess(), and Sabre\Event\Promise\wait().

FULFILLED

const Sabre\Event\Promise::FULFILLED = 1

The asynchronous operation has completed, and has a result.

Definition at line 33 of file Promise.php.

PENDING

const Sabre\Event\Promise::PENDING = 0

The asynchronous operation is pending.

Definition at line 28 of file Promise.php.

Referenced by Sabre\Event\coroutine().

REJECTED

const Sabre\Event\Promise::REJECTED = 2

The asynchronous operation has completed with an error.

Definition at line 38 of file Promise.php.

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/sabre/event/lib/Promise.php