README

A PHP Promise implementation following the Promises/A+ specification, built on top of Swoole coroutines for true asynchronous programming.

Features

• ✅ Promises/A+ specification compliant
• ✅ Built on Swoole coroutines for high-performance async operations
• ✅ Full promise chaining with then(), catch(), and finally()
• ✅ Static methods: Promise::all(), Promise::race(), Promise::any()
• ✅ Async/await syntax support with async() and await() functions
• ✅ Type-safe with PHP 8.2+ features
• ✅ Comprehensive test suite

Requirements

• PHP 8.2 or higher
• Swoole extension (recommended 5.0+)

Installation

Install via Composer:

composer require jefyokta/php-promise

Basic Usage

Creating and Resolving Promises

use JefyOkta\PhpPromise\Promise;

$promise = new Promise(function ($resolve, $reject) {
    // Do some async work
    $resolve('Success!');
});

$result = $promise->wait(); // 'Success!'

Promise Chaining

Promise::resolve(2)
    ->then(fn($x) => $x * 3)
    ->then(fn($x) => $x + 1)
    ->then(fn($x) => "Result: $x")
    ->wait(); // 'Result: 7'

Error Handling

Promise::resolve(10)
    ->then(fn($x) => $x / 0) // This will throw DivisionByZeroError
    ->catch(fn($error) => "Caught: " . $error->getMessage())
    ->wait(); // 'Caught: Division by zero'

Async/Await Syntax

use function JefyOkta\PhpPromise\async;
use function JefyOkta\PhpPromise\await;

async(function () {
    $result1 = await(async(fn() => 42)());
    $result2 = await(async(fn() => 58)());

    return $result1 + $result2;
})()->wait(); // 100

Promise.all()

$promises = [
    async(fn() => 1)(),
    async(fn() => 2)(),
    async(fn() => 3)(),
];

$result = Promise::all($promises)->wait(); // [1, 2, 3]

Promise.race()

$promises = [
    async(function () {
        Swoole\Coroutine::sleep(0.1);
        return 'slow';
    })(),
    async(function () {
        Swoole\Coroutine::sleep(0.05);
        return 'fast';
    })(),
];

$result = Promise::race($promises)->wait(); // 'fast'

Promise.any()

$promises = [
    Promise::reject('error1'),
    Promise::resolve('success'),
    Promise::reject('error2'),
];

$result = Promise::any($promises)->wait(); // 'success'

API Reference

Promise Class

Constructor

new Promise(?callable $executor = null)

Creates a new Promise. The executor function receives resolve and reject callbacks.

Instance Methods

• then(?callable $onFulfilled, ?callable $onRejected): Promise - Chains fulfillment/rejection handlers
• catch(callable $onRejected): Promise - Chains rejection handler
• finally(callable $onFinally): Promise - Chains cleanup handler
• wait(): mixed - Blocks until promise settles and returns value

Static Methods

• Promise::resolve(mixed $value): Promise - Creates a resolved promise
• Promise::reject(mixed $reason): Promise - Creates a rejected promise
• Promise::all(array $promises): Promise - Waits for all promises to resolve
• Promise::race(array $promises): Promise - Resolves/rejects with first settled promise
• Promise::any(array $promises): Promise - Resolves with first fulfilled promise

Functions

async(callable $fn): Asynchronous

$asyncFn = async(fn($x) => $x * 2);
$promise = $asyncFn(5); // Promise that resolves to 10

await(Promise $promise): mixed

$result = await($promise); // Wait for promise resolution

Swoole Integration

This library leverages Swoole coroutines for true asynchronous execution. Make sure Swoole is installed and the coroutine environment is available.

// Inside a coroutine context
Swoole\Coroutine\run(function () {
    $promise = async(function () {
        Swoole\Coroutine::sleep(1);
        return 'done';
    })();

    $result = await($promise);
    echo $result; // 'done' after 1 second
});

Testing

composer test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Add tests for new features
2. Follow PSR-12 coding standards
3. Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Jepi Oktamipa - Creator
• Built with Swoole coroutines
• Inspired by JavaScript Promises/A+ specification