PHPackages                             async-interop/promise - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. async-interop/promise

ActiveLibrary[Queues & Workers](/categories/queues)

async-interop/promise
=====================

A promise interface for interoperability in async operations.

v0.4.1(9y ago)652.5k↓50%3[3 issues](https://github.com/async-interop/promise/issues)1MITPHPPHP >=5.4.0

Since May 30Pushed 9y ago19 watchersCompare

[ Source](https://github.com/async-interop/promise)[ Packagist](https://packagist.org/packages/async-interop/promise)[ RSS](/packages/async-interop-promise/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (3)Versions (6)Used By (1)

Promise
=======

[](#promise)

The purpose of this specification is to provide a common interface for simple placeholder objects returned from async operations. This allows libraries and components from different vendors to create coroutines regardless of the placeholder implementation used. This specification is not designed to replace promise implementations that may be chained. Instead, the common interface may be extended by promise implementations.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119).

A `Promise` represents the eventual result of an asynchronous operation. Interaction with a `Promise` happens through its `when()` method, which registers a callback to receive either a `Promise`'s eventual value, or reason for failure.

`Promise` is the fundamental primitive in asynchronous programming. It should be as lightweight as possible, as any cost adds up significantly.

This specification defines the absolute minimum for interoperable coroutines, which can be implemented in PHP using generators.

This specification does not deal with how a `Promise` should be created, succeed, or fail, as only the consumption of `Promise` is required to be interoperable.

For further design explanations and notes, please refer to [the meta document](META.md).

Terminology
-----------

[](#terminology)

1. *Promise* is an object implementing `AsyncInterop\Promise` and conforming to this specification.
2. *Value* is any legal PHP value (including `null`), but not an instance of `AsyncInterop\Promise`.
3. *Error* is any value that can be thrown using the `throw` statement.
4. *Reason* is an error indicating why a `Promise` has failed.

States
------

[](#states)

A `Promise` MUST be in one of three states: `pending`, `succeeded`, `failed`.

A promise in … state `pending`- MAY transition to either the `succeeded` or `failed` state.

`succeeded`- MUST NOT transition to any other state.
- MUST have a value which MUST NOT change.\*

`failed`- MUST NOT transition to any other state.
- MUST have a reason which MUST NOT change.\*

- *Must not change* refers to the *reference* being immutable in case of an object, *not the object itself* being immutable.

A `Promise` is resolved once it either succeeded or failed.

Consumption
-----------

[](#consumption)

A `Promise` MUST implement `AsyncInterop\Promise` and thus provide a `when()` method to access its value or reason.

```