GitHub - true-async/php-async: The heart of asynchronous PHP, delivered as a core extension and implementing the TrueAsync ABI.

PHP TRUE ASYNC is an experimental PHP extension providing true asynchronous execution, tightly integrated at the core level. Write concurrent code using familiar PHP syntax — no callbacks, no promises, no framework required.

Features

Coroutines — Lightweight execution units that automatically suspend on blocking I/O, allowing other coroutines to run concurrently.
Scope — Structured concurrency container ensuring all child coroutines are properly awaited or cancelled, with hierarchical cancellation support.
Future — Represents a value not yet available, with chaining via map / catch / finally and lazy evaluation through await.
Channels — CSP-style primitives for safe data transfer between coroutines, with buffered queues and backpressure.
Context — Hierarchical key-value storage propagated implicitly through scopes and coroutines, similar to Go's context.Context.
Cancellation — Cooperative cancellation with critical section support (protect) and cascading cancellation through scope hierarchies.
Pool — Universal resource pool for managing reusable objects (connections, sockets) with health checks and circuit breaker patterns.
TaskGroup — High-level structured concurrency with multiple completion strategies (all / race / any) and concurrency limits.
PDO Pool — Transparent built-in connection pool for PDO, with automatic transaction management and health checks.
PDO Prepared Statement Cache — Opt-in per-connection LRU cache of server-side prepared statements (PDO::ATTR_POOL_STMT_CACHE_SIZE). Repeated prepare() of the same SQL reuses the cached server-side statement with zero wire traffic; measured ~2.9× on a tight prepare+execute+fetch loop. Supported on pdo_pgsql, pdo_mysql, pdo_sqlite. See docs/pdo-pool-stmt-cache-perf.md.
ThreadPool — Pool of OS threads for offloading CPU-bound or blocking PHP closures. submit() / map() return awaitable futures; coroutine: true mode runs each task as a coroutine inside its own scope (so tasks may await/use channels/IO without blocking the worker). Auto-detects worker count via Async\available_parallelism(). Includes graceful close(), hard cancel(), and per-worker bootloader hook.
Async\spawn_thread() — Spawn a single OS thread running an arbitrary PHP closure. Thread-safe channel via deep-copy snapshot (Async\ThreadChannel): send/recv suspend the coroutine, not the OS thread.
FileSystemWatcher — Persistent filesystem event observer with coalesced and raw event delivery modes.
70+ async-aware PHP functions — DNS, sockets, streams, cURL, PDO, MySQLi, PostgreSQL, process execution, sleep/timers, and more. All automatically non-blocking inside coroutines.

Companion project: TrueAsync Server

Looking for a production-ready way to put PHP TRUE ASYNC behind a network socket? See TrueAsync Server — a native PHP extension that runs a high-performance multi-protocol web server directly inside PHP, no separate process or reverse proxy. HTTP/1.1, HTTP/2, HTTP/3 (QUIC), WebSocket, SSE, and gRPC share a single TCP/UDP port via ALPN/Upgrade, and every connection runs on top of this event loop. Repository: github.com/true-async/server.

Installation

PHP TRUE ASYNC requires PHP 8.6+ and LibUV ≥ 1.49.0 (≥ 1.45.0 minimum, see io_uring warning below).

Full installation instructions and pre-built packages: true-async.github.io/download

Unix / macOS

Clone the PHP repository:

git clone https://github.com/true-async/php-src -b true-async-api ./php-src

Clone the extension into the ext directory:

git clone https://github.com/true-async/php-async ./php-src/ext/async

Install dependencies:
```
# Debian/Ubuntu
sudo apt-get install php-dev build-essential autoconf libtool pkg-config libuv1-dev

# macOS
brew install autoconf automake libtool pkg-config libuv
```
Note: LibUV 1.45.0+ is required. Older versions have a critical busy-loop issue in UV_RUN_ONCE mode causing high CPU usage.

Warning (io_uring): LibUV versions 1.45.0–1.48.x have a bug in the io_uring code path that causes a crash (Assertion 'req->type == UV_FS' failed in uv__poll_io_uring, src/unix/linux.c:1156) under sustained load when database connections are exhausted (e.g. PostgreSQL max_connections exceeded). The crash occurs because a non-filesystem completion event is processed by uv__poll_io_uring where only UV_FS requests are expected. This was fixed upstream between libuv 1.48 and 1.49 (io_uring was disabled by default in 1.49, and CQ overflow handling was fixed in PR #4601).

Recommended: Use LibUV ≥ 1.49.0 (tested stable with 1.52.1). If stuck on 1.48.x, set UV_USE_IO_URING=0 as a workaround.

io_uring SQPOLL (UV_USE_IO_URING=1): Do not enable SQPOLL mode. Benchmarks with FrankenPHP (4 workers, 1000 req/s, 5 SQL queries per request) show that SQPOLL significantly degrades performance compared to the default:

Default (io_uring FS only) SQPOLL (UV_USE_IO_URING=1)

avg latency 82 ms 908 ms

median 38 ms 63 ms

p95 106 ms 290 ms

req/s 993 856

dropped iterations 377 7745

With LibUV ≥ 1.49, the default (io_uring for FS operations, no SQPOLL) is optimal. Leave UV_USE_IO_URING unset.

	Default (io_uring FS only)	SQPOLL (`UV_USE_IO_URING=1`)
avg latency	82 ms	908 ms
median	38 ms	63 ms
p95	106 ms	290 ms
req/s	993	856
dropped iterations	377	7745

Configure and build:

./buildconf
./configure --enable-async
make && sudo make install

Windows

Set up php-sdk.
Build or install LibUV via vcpkg.
Copy LibUV headers to %PHP_SDK_PATH%\deps\include\libuv\ and libuv.lib to %PHP_SDK_PATH%\deps\lib\.

Build:

buildconf
configure --enable-async
nmake

Docker

docker build -t true-async-php .
docker run -it true-async-php bash
docker run --rm true-async-php php -m | grep true_async

IDE Support

PhpStorm stubs for autocompletion and inline docs are available in ide-stubs/.

Settings → PHP → Include Path → + → select the ide-stubs/ folder.

Documentation

Documentation — full reference and guides
Supported Functions — complete list of async-aware PHP functions
Download & Installation — packages and build instructions
cURL Integration Notes — known libcurl bugs, minimum version requirements, and architecture details

Contributing

Pull requests and suggestions are welcome! Please read CONTRIBUTING.md before starting. Also see: Contributing

License

MIT