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 (average of 3 runs). Revolt v1.0.8 tested with all four available drivers (StreamSelect, Ev, Event, UV). ext-eventloop using kqueue driver.

These benchmarks measure callback dispatch and scheduling throughput. The I/O backend (StreamSelect, Ev, Event, UV) primarily affects polling efficiency at high concurrency, not dispatch speed — that's why all four Revolt drivers show similar numbers here. ext-eventloop moves the entire dispatch path into C, which is where the difference comes from. Fiber performance is nearly identical because suspend()/resume() is handled by the Zend Engine directly.

Run the benchmarks yourself →

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 37 .phpt tests covering defer, delay, repeat, I/O watchers, signals, suspensions, error handling, and edge cases.

Changelog

Release notes are available in CHANGELOG.md.

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.