PHP 8.6 Native Async: STF IO Hooks Architecture Deep Dive

PHP Official Native Asynchronous Design: STF IO Hooks

The article details PHP's official native asynchronous design STF IO hooks , funded by the German Sovereign Tech Fund (STF) and authored by PHP Foundation core developers Arnaud Le Blanc and Jakub Zelenka. The design document STF IO hooks: operations, queues and offloading unifies five foundational components into a cohesive async stack.

Five Core Components Converge

Poll API — Merged into PHP 8.6 (release 2026-11-19). Responsible for readiness event multiplexing (Poll + Timer).

Stream Hooks → IO Hooks — Early draft upgraded to IO Hooks. Core foundation: intercepts blocking operations in core.

EINTR Handling (PR #22538) — In progress. Provides timeout deadline precision, signal delivery, in-use flags.

Async Core & Scheduler ABI (PR #22561) — Proposal stage. Extracted from TrueAsync; defines standard interface between PHP engine and coroutine scheduler.

ior completion library — Official project ready. Cross-platform completion driver integrating Linux io_uring, Windows IOCP, and thread pool fallback.

Key philosophy: "One hook, one unified abstraction." Everything is an Operation (network I/O, socket connect, even sleep()). Zero overhead and full compatibility: without an async Provider, PHP behaves identically (100% synchronous, zero performance cost); with a Provider (e.g., TrueAsync, Revolt), all blocking points automatically become async suspension points. Both Reactor (epoll/kqueue) and Proactor ( io_uring, IOCP) models coexist.

Four-Layer Architecture (Layer 0–3)

+--------------------------------------------------------------------------+
| Layer 3: Scheduler ABI (async-core RFC, Zend/zend_async_API.h)          |
|   (fully decoupled from I/O, only manages coroutine suspend/resume)     |
+--------------------------------------------------------------------------+
▲ (suspend / resume)
▼
+--------------------------------------------------------------------------+
| Layer 2: IO Hooks (php-src unified entry point: "tell upper layer this  |
|   operation will block", C struct + user-space Bridge)                 |
+--------------------------------------------------------------------------+
▲ (submit / complete)
▼
+--------------------------------------------------------------------------+
| Layer 1: Operation Queues                                               |
|   - Poll API (readiness: Poll / Timer / Ready)                          |
|   - Ring API (completion: all operations, backed by ior library)        |
+--------------------------------------------------------------------------+
▲
▼
+--------------------------------------------------------------------------+
| Layer 0: OS Kernel Backends                                             |
|   - Poll backends: epoll (Linux), kqueue (macOS/BSD), WSAPoll (Windows) |
|   - Ring backends: io_uring (Linux), IOCP (Windows), Thread Pool (fallback) |
+--------------------------------------------------------------------------+

Code Verification: Synchronous Code, Coroutine Execution

Scenario 1: Classic cURL Request

In the io_hooks_poc prototype branch, the test case uses unchanged synchronous code:

// Still the same classic synchronous code written for over a decade
$ch = curl_init("http://$addr/");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
// Blocking? Not anymore! Underlying non-blocking concurrency automatic
$body = curl_exec($ch);

Under the hood: curl_exec() is rewritten to use curl_multi_socket_action(), registering the socket descriptor and timeout wait entirely into IO Hooks . During the idle wait for the remote response, the current coroutine yields automatically, freeing the main thread to handle other requests.

Scenario 2: Minimal Scheduler Prototype (Native Fiber)

The document provides a tiny scheduler prototype:

$c = $this->queue->submit($op, \Fiber::getCurrent());
if ($c !== null) {
    /* Fast path: if system already has cached readiness at submit time,
       return directly, avoiding suspend and event-loop overhead */
    $this->inline++;
    return $c;
}

/* Slow path: data not ready, suspend current Fiber, wait for
   underlying queue completion, then scheduler resumes */
$this->inFlight++;
return \Fiber::suspend();

Built-in Functions Already Hooked in Prototype Branch (commit 056d9f8, 2026-09-29)

Streams & Network : stream_socket_client(), stream_socket_accept(), fread(), fwrite(), fgets(), stream_select() — Local HTTP interaction, multi-stream wait tests.

Low-level Sockets (ext/sockets) : socket_connect(), socket_accept(), socket_read(), socket_recv(), socket_write(), socket_send(), socket_select() — Socket basic ops, socket_select.

cURL Extension : curl_exec() (rewritten to libcurl socket API + Hook); curl_multi_select() (unified wait) — HTTP request tests, multi-select loop tests.

TLS/SSL : Handshake, encrypted read/write, timeout on tls:// streams — TLS encrypted interaction tests.

Filesystem : fread(), fwrite(), fsync(), fdatasync() (when underlying queue supports file async) — Non-blocking file read/write ops.

DNS & Timers : gethostbyname(), gethostbynamel(), gethostbyaddr(); sleep(), usleep(), time_nanosleep(), time_sleep_until() — Async DNS resolution, sleep timer tests.

Process & Signals : proc_close(), pclose(), pcntl_waitpid(), pcntl_sigwaitinfo(), pcntl_sigtimedwait() — Child process wait, signal handling tests.

Ecosystem Impact

1. End of "Forking php-src" Maintenance Burden

Projects like TrueAsync previously maintained a massive private php-src fork; every PHP release required painful rebasing. With official IO Hooks and Scheduler ABI , TrueAsync becomes a standard PECL extension . Developers simply run pecl install true_async on a clean official PHP to gain full true-async capabilities.

2. Seamless Drop-in: Legacy Systems Instantly Gain High Concurrency

Historically, refactoring old projects for coroutines meant replacing every file_get_contents, curl, and synchronous DB driver with async alternatives. Now, because the PHP kernel swaps these classic functions to non-blocking ops at the Streams layer, thousands of legacy systems and Composer packages can run on a coroutine scheduler with virtually zero business-code changes , immediately enjoying high-throughput benefits.

Roadmap: How Far Until Production?

Step 1: November 19, 2026 – PHP 8.6 GA Release

The foundational Poll API (multiplexing core) is already merged into PHP 8.6. Developers will get the new readiness multiplexing and high-precision timers on release day.

Step 2: Full Stack (IO Hooks + Async Scheduler ABI)

Async Scheduler ABI is in official PR review (PR #22561: https://github.com/php/php-src/pull/22561), while io_hooks_poc accelerates cURL shared multi-handle and deep boundary testing. After PHP 8.6 lands, the complete zero-perception async architecture (IO Hooks + ior completion driver) is expected to enter formal RFC voting, becoming the next core evolution milestone.

References

TrueAsync official long-read: "New Async PHP Core" – https://x.com/Edmondif143061/status/2105256640295366972

Jakub Zelenka design doc: "STF IO hooks: operations, queues and offloading" – https://gist.github.com/bukka/87359261a4bfaa572ce43c93c0554b55

PHP Async Scheduler ABI proposal: PR #22561 – https://github.com/php/php-src/pull/22561

PHP EINTR Handling: PR #22538 – https://github.com/php/php-src/pull/22538

PHP cross-platform completion driver ior: https://github.com/libior/ior