README

A native PHP extension that brings a high-performance event loop directly into the engine. Inspired by and API-compatible with Revolt -- not a replacement, but a native alternative written in C for zero-overhead async I/O.

Why? Revolt is an excellent userland library. This extension takes the same proven API design and moves it into a PHP extension, eliminating userland dispatch overhead and leveraging OS-level I/O primitives (epoll, kqueue, poll) directly from C.

Key Differences from Revolt

The API surface mirrors Revolt's, so migrating between the two is straightforward -- adjust the namespace and you're done.

Requirements

• PHP >= 8.1 (Fiber support required)
• A POSIX-compatible OS (Linux, macOS, FreeBSD, etc.)

Installation

Via PIE (recommended)

pie install axcherednikov/eventloop

From source

git clone https://github.com/axcherednikov/php-eventloop.git
cd php-eventloop

phpize
./configure --enable-eventloop
make
make test
sudo make install

Then enable the extension:

; php.ini or conf.d/eventloop.ini
extension=eventloop

Verify:

php -m | grep eventloop

Quick Start

<?php

use EventLoop\EventLoop;

// Defer a callback to the next loop tick
EventLoop::defer(function (string $callbackId) {
    echo "Deferred callback executed\n";
});

// Delay execution by 1.5 seconds
EventLoop::delay(1.5, function (string $callbackId) {
    echo "This runs after 1.5 seconds\n";
});

// Repeat every 500ms
$id = EventLoop::repeat(0.5, function (string $callbackId) {
    echo "Tick\n";
});

// Cancel the repeater after 3 seconds
EventLoop::delay(3, function () use ($id) {
    EventLoop::cancel($id);
});

EventLoop::run();

API Reference

All methods are static on EventLoop\EventLoop.

Scheduling

I/O Watchers

Signal Handling

Callback Management

Loop Control

Error Handling

Fiber Suspension

$fiber = new Fiber(function () {
    $suspension = EventLoop::getSuspension();

    EventLoop::defer(function () use ($suspension) {
        $suspension->resume('hello');
    });

    $value = $suspension->suspend(); // "hello"
    echo $value; // "hello"
});

$fiber->start();
EventLoop::run();

I/O Drivers

The extension automatically selects the best I/O driver available on your system at compile time. There is no manual configuration needed -- you always get optimal performance for your platform.

Selection priority: epoll > kqueue > poll > select. The first one that compiles and initializes successfully wins.

In practice this means:

• Linux servers (the most common deployment) get epoll -- handles thousands of connections with near-zero overhead
• macOS (local development) gets kqueue -- equally efficient
• Older or exotic systems gracefully fall back to poll or select

Check which driver is active:

echo EventLoop::getDriver(); // "epoll" on Linux, "kqueue" on macOS

Benchmarks

Environment: PHP 8.5.4, Apple M1 Max, macOS, 100,000 iterations. Revolt v1.0.8 with StreamSelectDriver (default, no ext-ev/ext-uv). ext-eventloop using kqueue driver.

Note: Revolt was tested with its default StreamSelectDriver. With ext-ev or ext-uv backends, Revolt's I/O performance would be higher, though callback dispatch overhead remains in PHP userland. Fiber performance is nearly identical because suspend()/resume() is handled by the Zend Engine in both cases.

Migrating from Revolt

The API contract is intentionally compatible. In most cases, a namespace swap is all you need:

- use Revolt\EventLoop;
+ use EventLoop\EventLoop;

If you use Revolt\EventLoop\Suspension:

- use Revolt\EventLoop\Suspension;
+ use EventLoop\Suspension;

Testing

make test

The extension ships with 26 .phpt tests covering defer, delay, repeat, I/O watchers, signals, suspensions, error handling, and edge cases.

Acknowledgements

This project is built on the ideas and API design of Revolt by Aaron Piotrowski, Niklas Keller, and contributors. Revolt's clean, well-thought-out API made it the natural foundation for a native implementation. Full credit to the Revolt team for defining the contract that this extension follows.

License

Licensed under the MIT License.