fyre/promise

An promise library.

v3.0.3 2024-10-30 10:58 UTC

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^11

MIT

• elusivecodes

README

FyrePromise is a free, open-source promise library for PHP.

It is a modern library, and features support for synchronous and asynchronous promises.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Async Promises
• Static Methods

Installation

Using Composer

composer require fyre/promise

In PHP:

use Fyre\Promise\Promise;

Basic Usage

• $callback is a Closure.

$promise = new Promise($callback);

The $callback should be expressed in the following format:

$callback = function(Closure $resolve, Closure $reject): void {
    $resolve();
};

Methods

Catch

Execute a callback if the Promise is rejected.

• $onRejected is a Closure that will execute when the Promise is rejected.

$promise->catch($onRejected);

This method will return a new Promise.

Finally

Execute a callback when the Promise is settled.

• $onFinally is a Closure that will execute when the Promise has settled.

$promise->finally($onFinally);

This method will return a new Promise.

Then

Execute a callback when the Promise is resolved.

• $onFulfilled is a Closure that will execute when the Promise is resolved.
• $onRejected is a Closure that will execute when the Promise is rejected, and will default to null.

$promise->then($onFulfilled, $onRejected);

This method will return a new Promise.

Async Promises

The \Fyre\Promise\AsyncPromise class extends the Promise class, while providing additional methods for handling asynchronous operations.

use \Fyre\Promise\AsyncPromise;

$promise = new AsyncPromise(function(Closure $resolve, Closure $reject): void {
    // this will be executed on a forked process
    sleep(3);

    $resolve(1);
})->then(function(int $value): void {
    // this will be executed on the main thread

    echo $value;
});

$promise->wait();

Cancel

Cancel the pending AsyncPromise.

• $message is a string representing the cancellation message.

$promise->cancel($message);

A cancelled promise will reject with a Fyre\Promise\Exceptions\CancelledPromiseException.

Wait

Wait for the AsyncPromise to settle.

$promise->wait();

Static Methods

Any

Wait for any promise to resolve.

• $promises is an iterable containing the promises or values to wait for.

$promise = Promise::any($promises);

This method will return a new Promise.

All

Wait for all promises to resolve.

• $promises is an iterable containing the promises or values to wait for.

$promise = Promise::all($promises);

This method will return a new Promise.

Await

Wait for a Promise to settle.

• $promise is the Promise to wait for.

try {
    $resolvedValue = Promise::await($promise);
} catch (Throwable $reason) {
    //...
}

Race

Wait for the first promise to resolve.

• $promises is an iterable containing the promises or values to wait for.

$promise = Promise::all($promises);

This method will return a new Promise.

Reject

Create a Promise that rejects.

• $reason is a Throwable representing the rejected reason, and will default to null.

$promise = Promise::reject($reason);

Resolve

Create a Promise that resolves.

• $value is the resolved value, and will default to null.

$promise = Promise::resolve($value);