The heart of asynchronous PHP, delivered as a core extension and implementing the TrueAsync ABI.
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.
map / catch / finally and lazy evaluation through await.context.Context.protect) and cascading cancellation through scope hierarchies.all / race / any) and concurrency limits.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.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.DNS, sockets, streams, cURL, PDO, MySQLi, PostgreSQL, process execution, sleep/timers, and more. All automatically non-blocking inside coroutines.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.
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
Clone the PHP repository:
git clone https://github.com/true-async/php-src -b true-async-api ./php-srcClone the extension into the ext directory:
git clone https://github.com/true-async/php-async ./php-src/ext/asyncInstall 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 libuvNote: LibUV 1.45.0+ is required. Older versions have a critical busy-loop issue in
UV_RUN_ONCEmode causing high CPU usage.
Warning (io_uring): LibUV versions 1.45.0–1.48.x have a bug in the
io_uringcode path that causes a crash (Assertion 'req->type == UV_FS' failedinuv__poll_io_uring,src/unix/linux.c:1156) under sustained load when database connections are exhausted (e.g. PostgreSQLmax_connectionsexceeded). The crash occurs because a non-filesystem completion event is processed byuv__poll_io_uringwhere onlyUV_FSrequests 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=0as 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_URINGunset.
Configure and build:
./buildconf
./configure --enable-async
make && sudo make installSet 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
nmakedocker build -t true-async-php .
docker run -it true-async-php bash
docker run --rm true-async-php php -m | grep true_asyncPhpStorm stubs for autocompletion and inline docs are available in ide-stubs/.
Settings → PHP → Include Path → + → select the ide-stubs/ folder.
Pull requests and suggestions are welcome! Please read CONTRIBUTING.md before starting. Also see: Contributing
PHP TRUE ASYNC — modern async PHP, today!
No open issues yet, or sync has not completed.