Awesome
English | 日本語
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/