README

AsyncPromise

What is the AsyncPromise?

The AsyncPromise is a library for processing concurrently on PHP which implementing similarity with Javascript's Promise.

Requirements

PHP 8.1 or higher
Swoole (if you use SwooleDriver)

How to install

You can install as following command:

$ composer require m3m0r7/async-promise

How to use

Get started

The Promise can be used in the same way JavaScript as following:

<?php

use AsyncPromise\Promise;

(new Promise(function (callable $resolve) {
    $resolve('resolved!');
}))->then(function ($result) {
    // Show `resolved!`
    echo $result;
});

You can receive an exception to chain with catch method.

<?php

use AsyncPromise\Promise;

(new Promise(function (callable $resolve) {
    throw new Exception('An error occurred');
}))->catch(function ($reason) {
    // Show `An error occurred`
    echo $reason;
});

Or you can process a rejection by the second parameter on a Promise callback function.

<?php

use AsyncPromise\Promise;

(new Promise(function (callable $_, callable $reject) {
    $reject('An error occurred');
}))->catch(function ($reason) {
    // Show `An error occurred`
    echo $reason;
});

And the then method can be multiple chained.

<?php

use AsyncPromise\Promise;

(new Promise(function (callable $resolve) {
    $resolve('resolved!');
}))->then(function ($result) {
    return 'nested chain: ' . $result;
})->then(function ($result) {
    // Show `nested chain: resolved!`
    echo $result;
});

After calling then or catch method, you can use finally if you want to run something.

<?php

use AsyncPromise\Promise;

(new Promise(function (callable $resolve) {
    $resolve('resolved!');
}))->then(function ($result) {
    return 'nested chain: ' . $result;
}, function ($reason) {
    echo $reason;
})->finally(function ($result) {
    echo "Finally was reached";
});

Promise::all(array)

The result is returned as a new Promise when all of the passed Promises are fulfilled until rejecting.

<?php

use AsyncPromise\Promise;

Promise::all([
    65535,
    'text',
    (new Promise(fn (callable $resolve) => $resolve('fulfilled1'))),
    ['key' => 'value'],
    (new Promise(fn (callable $resolve) => $resolve('fulfilled2'))),
])->then(function (array $values) {
    // Show as following:
    //
    // Array
    // (
    //    [0] => 65535
    //    [1] => text
    //    [2] => fulfilled1
    //    [3] => Array
    //        (
    //            [key] => value
    //        )
    //
    //    [4] => fulfilled2
    // )
    print_r($values);
});

It will run until reject as following:

<?php

use AsyncPromise\Promise;

Promise::all([
    65535,
    'text',
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected'))),
])->then(function (array $values) {
    // This statement is unreachable.
    print_r($values);
})->catch(function (string $reason) {
    // Show `rejected`
    echo $reason;
});

Promise::allSettled(array)

The result is returned as a new Promise when all of the passed Promises are processed.

<?php

use AsyncPromise\Promise;

Promise::allSettled([
    65535,
    'text',
    (new Promise(fn (callable $resolve) => $resolve('resolved'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected'))),
])->then(function (array $values) {
    foreach ($values as $value) {
        if ($value->status === Promise::FULFILLED) {
            // Show as following:
            //   fulfilled: 65535
            //   fulfilled: text
            //   fulfilled: resolved
            echo "{$value->status}: {$value->value}\n";
        }
        if ($value->status === Promise::REJECTED) {
            // Show as following:
            //   rejected: rejected
            echo "{$value->status}: {$value->reason}\n";
        }
    }
});

Promise::race(array)

The result is returned as a new Promise when one of the passed Promises is processed.

<?php

use AsyncPromise\Promise;

Promise::race([
    (new Promise(fn (callable $resolve) => $resolve('resolved1'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected1'))),
    (new Promise(fn (callable $resolve) => $resolve('resolved2'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected2'))),
])->then(function ($value) {
    // Show `resolved1`
    echo "{$value}\n";
});

Promise::any(array)

The result is returned as a new Promise when one of the passed Promises is fulfilled.

<?php

use AsyncPromise\Promise;

Promise::any([
    (new Promise(fn (callable $resolve) => $resolve('resolved1'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected1'))),
    (new Promise(fn (callable $resolve) => $resolve('resolved2'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected2'))),
])->then(function ($value) {
    // Show `resolved1`
    echo "{$value}\n";
});

And it is not fulfilled, it will chain to catch method.

<?php

use AsyncPromise\Promise;

Promise::any([
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected1'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected2'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected3'))),
    (new Promise(fn (callable $_, callable $reject) => $reject('rejected4'))),
])->catch(function (array $values) {
    // Show as following:
    //
    // Array
    // (
    //     [0] => rejected1
    //     [1] => rejected2
    //     [2] => rejected3
    //     [3] => rejected4
    // )
    print_r($values);
});

Promise::resolve(mixed)

It will resolve Promise.

<?php

use AsyncPromise\Promise;

Promise::resolve('resolved1')
    ->then(function (string $value) {
        // Show `resolved1`
        echo "resolved1\n";
    });

It will reject Promise.

<?php

use AsyncPromise\Promise;

Promise::reject('resolved1')
    ->catch(function (string $value) {
        // Show `resolved1`
        echo "resolved1\n";
    });

Promise::reject(string)

Drivers

You can choose to run concurrently driver. The AsyncPromise was implemented as following:

\AsyncPromise\Driver\SwooleDriver
\AsyncPromise\Driver\FiberDriver
\AsyncPromise\Driver\PcntlDriver (experimental)
\AsyncPromise\Driver\PolyfillDriver

To switch other driver:

Promise::setPromiseDriver(\AsyncPromise\Driver\SwooleDriver::class);

(new Promise(...))->then(...);

You must run a Promise in Promise::createContext(...) context if you use the SwooleDriver.

Promise::setPromiseDriver(\AsyncPromise\Driver\SwooleDriver::class);

Promise::createContext(function () {
    (new Promise(fn (callable $resolve) => $resolve('resolved with SwooleDriver')))
        // Show `resolved with SwooleDriver`
        ->then(fn ($result) => print($result));
});

You will get a benefit with concurrency when using SwooleDriver. The below command is getting SwooleDriver performance:

Promise::setPromiseDriver(\AsyncPromise\Driver\SwooleDriver::class);

// sleep function to be coroutinized.
\Swoole\Runtime::enableCoroutine(SWOOLE_HOOK_SLEEP);

Promise::createContext(function () {
    $start = time();
    Promise::all([
        new Promise(function (callable $resolve) {
            sleep(3);
            $resolve();
        }),
        new Promise(function (callable $resolve) {
            sleep(5);
            $resolve();
        }),
    ])->then(function ($values) use ($start) {
        // Show `Take 5 sec`
        echo "Take " . (time() - $start) . " sec";
    });
});

The PolyfillDriver is a virtual process driver when concurrency driver is not installed. Therefore the PolyfillDriver does not increase performance because which is running on synchronization. For example, to run above code; it will show Take 8 sec.

How to test

You can run tests as following commands:

./vendor/bin/phpunit tests/

m3m0r7 / async-promise

Maintainers

Details