README

Caution: This package is a work in progress and it manipulates process lifecycles using low-level and potentially unsafe techniques such as FFI for inter-process communication, and preserving state across process spawns. It is intended strictly for internal use (e.g., performance optimizations in Pest). Don't use this in production or use at your own risk—no guarantees are provided.

Pokio

Pokio is a dead simple Asynchronous API for PHP that just works! Here is an example:

$promiseA = async(function () {
    sleep(2);
    
    return 'Task 1';
});

$promiseB = async(function () {
    sleep(2);
    
    return 'Task 2';
});

// just takes 2 seconds...
[$resA, $resB] = await([$promiseA, $promiseB]);

echo $resA; // Task 1
echo $resB; // Task 2

Behind-the-scenes, Pokio uses the PCNTL extension to fork the current process and run the given closure in a child process. This allows you to run multiple tasks concurrently, without blocking the main process.

Also, for communication between the parent and child processes, Pokio uses FFI to create a shared memory segment, which allows you to share data between processes fast and efficiently.

However, unlike other libraries, if PCNTL or FFI are not available, Pokio will automatically fall back to sequential execution, so you can still use it without any issues.

Installation

Requires PHP 8.3+.

⚡️ Get started by requiring the package using Composer:

composer require nunomaduro/pokio:^0.1

Usage

async

The async global function returns a promise that will eventually resolve the value returned by the given closure.

$promise = async(function () {
    return 1 + 1;
});

var_dump(await($promise)); // int(2)

Similar to other promise libraries, Pokio allows you to chain methods to the promise (like then, catch, etc.).

The then method will be called when the promise resolves successfully. It accepts a closure that will receive 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)

Optionally, you may chain a catch method to the promise, which will be called if the given closure throws an exception.

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

var_dump(await($promise)); // string(16) "Rescued: Error"

If you don't want to use the catch method, you can also use native try/catch block.

$promise = async(function () {
    throw new Exception('Error');
});

try {
    await($promise);
} catch (Throwable $e) {
    var_dump('Rescued: ' . $e->getMessage()); // string(16) "Rescued: Error"
}

Similar to the catch method, you may also chain a finally method to the promise, which will be called regardless of whether the promise resolves successfully or throws an exception.

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

If you return a promise from the closure, it will be awaited automatically.

$promise = async(function () {
    return async(function () {
        return 1 + 1;
    });
});

var_dump(await($promise)); // int(2)

await

The await global function will block the current process until the given promise resolves.

$promise = async(function () {
    sleep(2);
    
    return 1 + 1;
});

var_dump(await($promise)); // int(2)

You may also pass an array of promises to the await function, which will be awaited simultaneously.

$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) }

Instead of using the await function, you can also invoke the promise directly, which will return the resolved value of the promise.

$promise = async(fn (): int => 1 + 2);

$result = $promise();

var_dump($result); // int(3)

Follow Nuno

Follow the creator Nuno Maduro:
- YouTube: youtube.com/@nunomaduro — Videos every weekday
- Twitch: twitch.tv/enunomaduro — Streams (almost) every weekday
- Twitter / X: x.com/enunomaduro
- LinkedIn: linkedin.com/in/nunomaduro
- Instagram: instagram.com/enunomaduro
- Tiktok: tiktok.com/@enunomaduro

License

Pokio was created by Nuno Maduro under the MIT license.

nunomaduro / pokio

Maintainers

Details