ReactPHP Promise

In this library, a Deferred represents a computation or unit of work that may not have completed yet (the process), while a Promise represents the eventual result of that computation (the placeholder).

Typically, you create a Deferred object to manage an asynchronous operation. You then use $deferred->promise() to obtain a Promise that you can return to consumers. The Deferred object retains the authority to resolve or reject that promise.

Install the latest supported version of the library using Composer:

composer require react/promise:^3.2

This project supports PHP 7.1 through PHP 8+. If you need to support older PHP versions, you can target multiple major versions simultaneously:

composer require "react/promise:^3 || ^2 || ^1"

The then() method registers fulfillment and rejection handlers. It returns a new promise that implements the transformation, allowing for promise chaining (pipelines).

• $onFulfilled (optional): Called with the fulfillment value. If it returns a value, the new promise fulfills with that value. If it returns a promise, the new promise follows that promise.
• $onRejected (optional): Called with the rejection reason. If it throws or returns a rejected promise, the new promise rejects.

Guarantees:

1. Only one of $onFulfilled or $onRejected will be called.
2. Handlers will never be called more than once.

$transformedPromise = $promise->then(callable $onFulfilled = null, callable $onRejected = null);

The library provides several static functions to manage collections of promises:

• resolve(mixed $promiseOrValue): Creates a promise for a value or a thenable.
• reject(\Throwable $reason): Creates a rejected promise.
• all(iterable $promisesOrValues): Returns a promise that resolves only when all items in the collection have resolved. The resolution value is an array of all results.
• race(iterable $promisesOrValues): Returns a promise that settles as soon as the first promise in the collection settles (either fulfills or rejects).
• any(iterable $promisesOrValues): Returns a promise that resolves when any one item resolves. It only rejects if all items are rejected (returning a CompositeException).

Note: All these collection functions support cancellation; cancelling the returned promise will cancel all promises in the collection.

Use React\Promise\set_rejection_handler() to define a global callback for unhandled promise rejections. This is useful for custom logging or error reporting.

• The callback must accept a single \Throwable argument (or null to restore the default handler).
• The callback must not throw an exception, or the program will terminate with a fatal error.
• It returns the previous handler or null if the default was used.

Use the React\Promise\Promise constructor to create a promise where the state is controlled by a resolver function.

• $resolver: A function called immediately. It receives $resolve and $reject callbacks.
• $canceller (optional): A function called when $promise->cancel() is invoked. It is used to abort ongoing operations (like network requests).

If the resolver or canceller throws an exception, the promise is automatically rejected with that exception.

$resolver = function (callable $resolve, callable $reject) {
    $resolve($awesomeResult);
    // or $reject($nastyError);
};

$canceller = function () {
    throw new Exception('Promise cancelled');
};

$promise = new React\Promise\Promise($resolver, $canceller);

The finally() method allows you to execute code when a promise is either fulfilled or rejected, regardless of the outcome. It is used for cleanup tasks (similar to a synchronous finally block).

• The callback passed to finally() receives no arguments.
• If the original promise fulfills and the finally callback succeeds, the new promise fulfills with the original value.
• If the original promise rejects and the finally callback succeeds, the new promise rejects with the original reason.
• If the finally callback throws or returns a rejected promise, the new promise will reject with that new error/reason.

$newPromise = $promise->finally(callable $onFulfilledOrRejected);

The catch() method is a shortcut for $promise->then(null, $onRejected). It allows you to handle rejections in a promise chain.

You can type-hint the $reason argument in your callback to catch only specific types of errors. Other errors will automatically propagate down the chain.

$promise
    ->catch(function (\RuntimeException $reason) {
        // Only catch \RuntimeException instances
    })
    ->catch(function (\Throwable $reason) {
        // Catch all other errors
    });

The cancel() method notifies the creator of the promise that the result is no longer needed.

Note: Calling cancel() has no effect if the promise has already been settled (fulfilled or rejected).

$promise->cancel();

When using promise combinators like some() or any(), a promise may be rejected with multiple errors if the conditions for success are not met (e.g., too many input promises reject). In these cases, the library throws a React\Promise\Exception\CompositeException.

You can retrieve the collection of individual errors by calling the getThrowables() method on the caught exception.