Repository files navigation

Async utilities forReactPHP.

This library allows you to manage async control flow. It provides a number ofcombinators forPromise-based APIs.Instead of nesting or chaining promise callbacks, you can declare them as alist, which is resolved sequentially in an async manner.React/Async will not automagically change blocking code to be async. You needto have an actual event loop and non-blocking libraries interacting with thatevent loop for it to work. As long as you have a Promise-based API that runs inan event loop, it can be used with this library.

Table of Contents

• Usage
  • await()
  • delay()
  • parallel()
  • series()
  • waterfall()
• Todo
• Install
• Tests
• License

This lightweight library consists only of a few simple functions.All functions reside under theReact\Async namespace.

The below examples refer to all functions with their fully-qualified names like this:

React\Async\await(…);

As of PHP 5.6+ you can also import each required function into your code like this:

usefunctionReact\Async\await;await(…);

Alternatively, you can also use an import statement similar to this:

useReact\Async;Async\await(…);

Theawait(PromiseInterface $promise): mixed function can be used toblock waiting for the given$promise to be fulfilled.

$result =React\Async\await($promise);

This function will only return after the given$promise has settled, i.e.either fulfilled or rejected.

While the promise is pending, this function will assume control over the eventloop. Internally, it willrun() thedefault loopuntil the promise settles and then callsstop() to terminate execution of theloop. This means this function is more suited for short-lived promise executionswhen using promise-based APIs is not feasible. For long-running applications,using promise-based APIs by leveraging chainedthen() calls is usually preferable.

Once the promise is fulfilled, this function will return whatever the promiseresolved to.

Once the promise is rejected, this will throw whatever the promise rejectedwith. If the promise did not reject with anException orThrowable (PHP 7+),then this function will throw anUnexpectedValueException instead.

try {$result =React\Async\await($promise);// promise successfully fulfilled with $resultecho'Result:' .$result;}catch (Throwable$e) {// promise rejected with $eecho'Error:' .$e->getMessage();}

Thedelay(float $seconds): void function can be used todelay program execution for duration given in$seconds.

React\Async\delay($seconds);

This function will only return after the given number of$seconds haveelapsed. If there are no other events attached to this loop, it will behavesimilar to PHP'ssleep() function.

echo'a';React\Async\delay(1.0);echo'b';// prints "a" at t=0.0s// prints "b" at t=1.0s

Unlike PHP'ssleep() function,this function may not necessarily halt execution of the entire process thread.Instead, it allows the event loop to run any other events attached to thesame loop until the delay returns:

echo'a';Loop::addTimer(1.0,function () {echo'b';});React\Async\delay(3.0);echo'c';// prints "a" at t=0.0s// prints "b" at t=1.0s// prints "c" at t=3.0s

This behavior is especially useful if you want to delay the program executionof a particular routine, such as when building a simple polling or retrymechanism:

try {something();}catch (Exception$e) {// in case of error, retry after a short delayReact\Async\delay(1.0);something();}

Because this function only returns after some time has passed, it can beconsideredblocking from the perspective of the calling code. While thedelay is running, this function will assume control over the event loop.Internally, it willrun() thedefault loopuntil the delay returns and then callsstop() to terminate execution of theloop. This means this function is more suited for short-lived promise executionswhen using promise-based APIs is not feasible. For long-running applications,using promise-based APIs by leveraging chainedthen() calls is usually preferable.

Internally, the$seconds argument will be used as a timer for the loop so thatit keeps running until this timer triggers. This implies that if you pass areally small (or negative) value, it will still start a timer and will thustrigger at the earliest possible time in the future.

Theparallel(array<callable():PromiseInterface<mixed>> $tasks): PromiseInterface<array<mixed>> function can be usedlike this:

<?phpuseReact\EventLoop\Loop;useReact\Promise\Promise;React\Async\parallel([function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for a whole second');            });        });    },function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for another whole second');            });        });    },function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for yet another whole second');            });        });    },])->then(function (array$results) {foreach ($resultsas$result) {var_dump($result);    }},function (Exception$e) {echo'Error:' .$e->getMessage() .PHP_EOL;});

Theseries(array<callable():PromiseInterface<mixed>> $tasks): PromiseInterface<array<mixed>> function can be usedlike this:

<?phpuseReact\EventLoop\Loop;useReact\Promise\Promise;React\Async\series([function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for a whole second');            });        });    },function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for another whole second');            });        });    },function () {returnnewPromise(function ($resolve) {            Loop::addTimer(1,function ()use ($resolve) {$resolve('Slept for yet another whole second');            });        });    },])->then(function (array$results) {foreach ($resultsas$result) {var_dump($result);    }},function (Exception$e) {echo'Error:' .$e->getMessage() .PHP_EOL;});

Thewaterfall(array<callable(mixed=):PromiseInterface<mixed>> $tasks): PromiseInterface<mixed> function can be usedlike this:

<?phpuseReact\EventLoop\Loop;useReact\Promise\Promise;$addOne =function ($prev =0) {returnnewPromise(function ($resolve)use ($prev) {        Loop::addTimer(1,function ()use ($prev,$resolve) {$resolve($prev +1);        });    });};React\Async\waterfall([$addOne,$addOne,$addOne])->then(function ($prev) {echo"Final result is$prev\n";},function (Exception$e) {echo'Error:' .$e->getMessage() .PHP_EOL;});

• Implement queue()

The recommended way to install this library isthrough Composer.New to Composer?

This project followsSemVer.This will install the latest supported version from this branch:

composer require react/async:^2.2

See also theCHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHPextensions and supports running on legacy PHP 5.3 through current PHP 8+.It'shighly recommended to use the latest supported PHP version for this project.

To run the test suite, you first need to clone this repo and then install alldependenciesthrough Composer:

composer install

To run the test suite, go to the project root and run:

vendor/bin/phpunit

MIT, seeLICENSE file.

This project is heavily influenced byasync.js.