Webman TypePHP AOT Plugin: Compile PHP to Native Linux Binaries via Docker

Introduction

PHP deployment traditionally requires a pre-installed PHP runtime, extensions, and Composer dependencies on the target server. Distribution, source-code protection, and environment consistency remain pain points. TypePHP, an AOT compiler from the Swoole team, translates PHP to C++ and then to native machine code, producing standalone ELF binaries that run without the Zend VM. However, adapting TypePHP for resident-memory frameworks like Webman is difficult due to framework internals, coroutine components, and closure validation causing compile failures or runtime crashes.

What is tinywan/webman-typephp

tinywan/webman-typephp

is a Webman ecosystem plugin that wraps the entire TypePHP AOT build flow. It automatically generates AOT entry files and Linux build configuration, then delegates compilation to a fixed-version Docker builder image, outputting a ready-to-distribute dist/ directory. Developers only need PHP, Composer, and Docker on the host — no manual C++ compiler, Clang, or TypePHP toolchain installation.

Core principle: business logic stays in PHP with no large-scale rewrites; the plugin patches framework internals, compiles compatible code to native ELF via TypePHP AOT, and falls back to a Zend-compatible path for dynamic logic that cannot be compiled, enabling hybrid execution.

Quick Start

1. Install the plugin

composer require tinywan/webman-typephp --dev

2. Environment pre-check

php webman typephp:doctor

3. Compile and package

# Default build, outputs dist directory
php webman typephp:package

# Force overwrite existing dist, auto-backup old directory
php webman typephp:package --force

# Refresh main.php entry file, old entry auto-backed up
php webman typephp:package --refresh-main

# Specify custom Docker builder image
php webman typephp:package --image=tinywan/typephp-webman-builder:v0.1.0

4. Server deployment and startup

Upload the dist directory to a Linux x86_64/glibc server:

cd dist
./start.sh start

Standard Workerman management commands are supported:

./start.sh start -d
./start.sh status
./start.sh stop
./start.sh restart
# Direct binary wrapper script
./webman-server start

Artifact Directory Structure

dist/
├── webman-server.bin   # TypePHP-compiled native ELF binary
├── webman-server       # Startup wrapper script
├── start.sh            # Workerman standard start/stop script
├── libphp.so           # PHP core runtime shared library
├── libphpx.so          # PHPX runtime shared library
├── php.ini             # Standalone pure PHP runtime config
├── ext/                # PHP extension .so files
├── lib/                # Collected system dependency libraries
├── runtime/            # Log and cache runtime directory
├── build-manifest.json # Build metadata for traceability
├── config/             # Business configuration
├── public/             # Static assets
└── app/view/           # View templates

Note: the lib/ directory carries all dynamic dependencies required for compilation; glibc and the system loader are still provided by the target server OS.

Plugin Configuration

Configuration file:

config/plugin/tinywan/typephp/app.php

return [
    'enable' => true,
    'docker' => [
        'enabled' => true,
        'image' => 'tinywan/typephp-webman-builder:v0.1.0',
    ],
    'build' => [
        'output_name' => 'webman-server',
        'dist_dir' => 'dist',
        'clean_build' => true,
    ],
];

Build Demonstration

Environment check

PS D:\tinywan\typephp\webman> php webman typephp:doctor
=== TypePHP Environment Diagnostic Tool ===
• PHP Version: 8.5.10 [OK]
• Docker: Docker version 29.7.2, build a7dcaa6 [OK - Required for Phase 1]
• Host Clang Compiler: Not installed [OK - Handled inside Docker builder]

Binary compilation

D:\tinywan\typephp\webman> php webman typephp:package

[TypePHP] Preparing build files for Webman project...
[1/3] Verified AOT entrypoint: main.php
[2/3] Generated compiler config: project.linux.yml
[2/3] Generated flattened AOT sources: .typephp/build/helpers.php, .typephp/build/fast-route-functions.php
[2/3] Generated nullable-static AOT sources: .typephp/build/coroutine-context.php, .typephp/build/coroutine-wait-group.php, .typephp/build/coroutine-barrier.php
[2/3] Generated variadic-handler AOT sources: .typephp/build/workerman-worker.php, .typephp/build/workerman-tcp-connection.php, .typephp/build/workerman-async-tcp-connection.php, .typephp/build/workerman-select.php, .typephp/build/webman-file.php
[3/3] Running TypePHP AOT compilation container (tinywan/typephp-webman-builder:v0.0.17)...
Unable to find image 'tinywan/typephp-webman-builder:v0.0.17' locally
Digest: sha256:3d040e8135c92717167434858c23bbfad5cc5563dabd044e5318193cd85aa654
Status: Downloaded newer image for tinywan/typephp-webman-builder:v0.0.17
[INFO] Compiling Linux x86_64 glibc binary (job=8)...
Initialized platform/backend: Linux + GCC (g++)
[Scanning 12/51] app ...
[Scanning 13/51] vendor/workerman/workerman/src ...
[Scanning 14/51] vendor/workerman/webman-framework/src ...
[Scanning 15/51] vendor/workerman/coroutine/src ...
[Scanning 16/51] vendor/psr ...
[Scanning 51/51] vendor/monolog/monolog/src/Monolog/Processor ...
[Analyzing] Pre-checking native class declarations across 173 files...
[1/173] 1% native/20260907T074248Z-1/main.php
...
[129/129] 100% native/20260907T074248Z-1/.typephp/build/fast-route-functions.cc
Successfully compiled 129 files
g++ '@/native/20260907T074248Z-1/build/webman_server.rsp' -o '/native/20260907T074248Z-1/build/webman_server' -L '/opt/typephp/vendor/swoole/phpx/lib' -L '/usr/lib' -lphpx -lphp -lgmp -lgmpxx -lmpfr -lstdc++
[Build successful]: /native/20260907T074248Z-1/build/webman_server
[INFO] Copying PHP extensions from /usr/lib/php/20240924 to dist/ext/ ...
cp: '/native/20260907T074248Z-1/.typephp/out-20260907T074248Z-1/lib/libphp.so' and '/native/20260907T074248Z-1/.typephp/out-20260907T074248Z-1/lib/libphp.so' are the same file
[SUCCESS] Portable directory created: dist (run ./start.sh from it)
🎉 Successfully built portable-dir: dist/webman-server
Run command: cd dist && ./start.sh start
[post] Neutralized phar class constants in 1 config file(s): plugin/webman/console/app.php

Related Documentation

TypePHP AOT official docs: https://swoole.com/aot/zh

Project repository: https://github.com/Tinywan/webman-typephp

Issue tracker: https://github.com/Tinywan/webman-typephp/issues

TypePHP plugin proposal: TYPEPHP_PLUGIN_PROPOSAL.md

Release guide: RELEASING.md

Summary

TypePHP AOT opens a native compilation path for PHP, but direct Webman integration has a very high barrier. The tinywan/webman-typephp plugin closes the framework adaptation gap and uses Docker to shield compiler complexity, letting Webman developers experience low-cost PHP AOT native binary delivery.

It is not a universal solution; currently it best fits scenarios needing distribution, source protection, or CPU-intensive workloads. I/O-heavy web services see limited gains, and TypePHP itself is still evolving. Nevertheless, this represents a valuable practice for the Webman ecosystem in the PHP native compilation direction.