Boost PHP Concurrency with Pokio: Async API Guide and Code Samples

Introduction

Pokio is a simple, easy‑to‑use PHP asynchronous API that works with minimal configuration. It runs tasks concurrently by forking the current process with the PCNTL extension and communicating via shared memory created with FFI. If PCNTL or FFI are unavailable, Pokio gracefully falls back to sequential execution.

Installation

Requires PHP 8.3 or higher.

Install the package with Composer:

composer require nunomaduro/pokio:^0.1

Usage

async

The global async function returns a promise that resolves to the value returned by the supplied closure.

$promise = async(function () {
    return 1 + 1;
});
var_dump(await($promise)); // int(2)

Promises can be chained with then, catch, and finally methods.

then

The then method is called when the promise resolves successfully; it receives the resolved value as its first argument.

$promise = async(fn(): int => 1 + 2)
    ->then(fn($result): int => $result + 2)
    ->then(fn($result): int => $result * 2);
$result = await($promise);
var_dump($result); // int(10)

catch

The catch method handles exceptions thrown inside the closure.

$promise = async(function () {
    throw new Exception('Error');
})->catch(function (Throwable $e) {
    return 'Rescued: ' . $e->getMessage();
});
var_dump(await($promise)); // string(16) "Rescued: Error"

finally

The finally method runs regardless of whether the promise resolves or throws.

$promise = async(function (): void {
    throw new RuntimeException('Exception 1');
})->finally(function () use (&$called) {
    echo "Finally called
";
});

await

The global await function blocks the current process until the given promise resolves. It also accepts an array of promises and waits for all of them.

$promiseA = async(function () {
    sleep(2);
    return 1 + 1;
});
$promiseB = async(function () {
    sleep(2);
    return 2 + 2;
});
var_dump(await([$promiseA, $promiseB])); // array(2) { [0]=> int(2) [1]=> int(4) }

Promises can also be invoked directly to obtain their resolved value without using await:

$promise = async(fn(): int => 1 + 2);
$result = $promise();
var_dump($result); // int(3)

If a closure returns another promise, Pokio automatically awaits it.