TrueAsync PHP

Pre-built PHP binaries and Docker images with native async/coroutine support via the TrueAsync extension.

Quick Start

Docker (Linux)

docker pull trueasync/php-true-async:8.6
docker run --rm trueasync/php-true-async:8.6 php -v

Each image includes both php (CLI) and php-fpm.

Available tags:

Tag	Base	Description
8.6	Ubuntu 24.04	Full image with cli + fpm
8.6-alpine	Alpine 3.20	Lightweight image with cli + fpm
8.6-frankenphp	Ubuntu 24.04	FrankenPHP — Caddy + async PHP worker
latest	Ubuntu 24.04	Alias for 8.6
latest-frankenphp	Ubuntu 24.04	Alias for 8.6-frankenphp

FrankenPHP (async worker mode)

FrankenPHP is a Go-based PHP app server built on top of Caddy. The TrueAsync variant runs PHP as a persistent async worker — one PHP script stays loaded and handles requests as coroutines via the TrueAsync event loop.

docker pull trueasync/php-true-async:latest-frankenphp
docker run --rm -p 8080:8080 trueasync/php-true-async:latest-frankenphp

Then open http://localhost:8080 — the bundled demo page shows live runtime stats (PHP version, active coroutines, memory).

To use your own entrypoint:

docker run --rm -p 8080:8080 \
  -v ./my-app:/app \
  -v ./Caddyfile:/etc/caddy/Caddyfile \
  trueasync/php-true-async:latest-frankenphp

Example Caddyfile with async worker:

{
    admin off
    frankenphp {}
}

:8080 {
    root * /app
    php_server {
        index off
        file_server off
        worker {
            file /app/entrypoint.php
            num 1
            async
            buffer_size 20
            match /*
        }
    }
}

Example entrypoint.php:

<?php
use FrankenPHP\HttpServer;
use FrankenPHP\Request;
use FrankenPHP\Response;

set_time_limit(0);

HttpServer::onRequest(function (Request $request, Response $response): void {
    $response->setStatus(200);
    $response->setHeader('Content-Type', 'text/plain');
    $response->write('Hello from TrueAsync!');
    $response->end();
});

Build from Source (Linux)

curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-linux.sh | bash

An interactive wizard will guide you through the build configuration: extensions, FrankenPHP, debug mode, install path, and PATH setup.

For non-interactive use (CI/scripts):

# Standard build
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-linux.sh | \
  NO_INTERACTIVE=true EXTENSIONS=all SET_DEFAULT=true bash

# With FrankenPHP
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-linux.sh | \
  NO_INTERACTIVE=true EXTENSIONS=all BUILD_FRANKENPHP=true SET_DEFAULT=true bash

Supported distros: Ubuntu, Debian (apt-based).

Build from Source (macOS)

curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-macos.sh | bash

Requires Homebrew. Supports both Apple Silicon (ARM) and Intel Macs.

For non-interactive use:

# Standard build
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-macos.sh | \
  NO_INTERACTIVE=true EXTENSIONS=all SET_DEFAULT=true bash

# With FrankenPHP
curl -fsSL https://raw.githubusercontent.com/true-async/releases/master/installer/build-macos.sh | \
  NO_INTERACTIVE=true EXTENSIONS=all BUILD_FRANKENPHP=true SET_DEFAULT=true bash

Windows

Quick install (PowerShell):

irm https://raw.githubusercontent.com/true-async/releases/master/installer/install.ps1 | iex

Manual install:

1. Go to Releases
2. Download the archive:
   • Release — for general use
   • Debug — for PHP/extension development (includes debug symbols and assertions)
3. Verify the SHA256 checksum from sha256sums.txt
4. Extract to your preferred location
5. Add the directory to your PATH

Build Options

The build-from-source scripts (build-linux.sh, build-macos.sh) support these options:

Option	Env Variable	Default	Description
--prefix DIR	INSTALL_DIR	$HOME/.php-trueasync	Installation directory
--set-default	SET_DEFAULT=true	false	Add to PATH as default php
--debug	DEBUG_BUILD=true	false	Build with debug symbols
--extensions PRESET	EXTENSIONS	standard	Extension preset: standard, xdebug, all (see below)
--no-xdebug	NO_XDEBUG=true	false	Exclude Xdebug from build
--frankenphp	BUILD_FRANKENPHP=true	false	Build FrankenPHP binary (Caddy-based async server)
--no-latest-curl	BUILD_LATEST_CURL=false	true	Skip building libcurl 8.12.0 (async uploads fallback)
--jobs N	BUILD_JOBS	auto	Parallel make jobs
--branch NAME	PHP_BRANCH	from config	Override php-src branch
--no-interactive	NO_INTERACTIVE=true	false	Skip interactive wizard

Extension presets (--extensions):

Preset	Xdebug	Description
standard	No	async + core PHP extensions
xdebug	Yes	standard + Xdebug debugger
all	Yes	everything (same as xdebug)

FrankenPHP is opt-in via --frankenphp / BUILD_FRANKENPHP=true regardless of the preset. Requires Go 1.26+ (installed automatically if not found).

By default, the installer builds libcurl 8.12.0 from source. This is required for fully async file uploads — libcurl >= 8.11.1 fixes PAUSE/unpause bugs (curl#15627) that caused intermittent timeouts. Use --no-latest-curl to skip this and use the system libcurl (async uploads will fall back to synchronous reads).

TrueAsync PHP is not added to PATH by default to avoid conflicts with your system PHP. Use --set-default to make it the default php.

Management

After installation, use the php-trueasync command:

php-trueasync rebuild     # Rebuild from latest source
php-trueasync version     # Show installed version
php-trueasync uninstall   # Remove TrueAsync PHP

Verify Installation

php -v
php -m | grep async

What's Included

Extension	Description
async	TrueAsync coroutine engine with libuv reactor
xdebug	Debugger and profiler (optional)

Standard PHP extensions: curl, mbstring, openssl, pdo, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, sockets, and more.

Platforms

Platform	Method	Variants	Status
Linux	Docker	Ubuntu 24.04, Alpine 3.20, FrankenPHP	✅
Linux	Build from source	Ubuntu/Debian (apt)	✅
macOS	Build from source	ARM + Intel (Homebrew)	✅
Windows	Pre-built binaries	Release, Debug (x64)	✅

Configuration

Build parameters are defined in build-config.json:

• PHP source repository and branch
• Extensions to include
• Configure flags per platform

Links

• Docker Hub — Docker images
• TrueAsync PHP Source — PHP fork with async API
• TrueAsync Extension — libuv-based async implementation
• TrueAsync Xdebug — Xdebug with async support
• TrueAsync FrankenPHP — FrankenPHP fork with async worker support

License

MIT