📖 简介

tinywan/webman-typephp 是面向 Webman 2.x 的 TypePHP AOT 构建插件。它会从现有 Webman 项目生成 AOT 入口和 Linux 编译配置，再交给固定版本的 Docker builder 完成编译，最后整理出可以复制到目标服务器的 dist/ 目录。

宿主机只需要 PHP、Composer 和 Docker，不需要安装 C++、Clang 或 TypePHP 编译工具链。

🚀 快速开始

1. 安装插件

在 Webman 项目根目录执行：

composer require tinywan/webman-typephp --dev

2. 检查环境

确认 PHP 版本、Docker CLI 和 Docker daemon 可用：

php webman typephp:doctor

3. 编译打包

# 默认输出到 dist/
php webman typephp:package

# dist/ 已存在时，显式确认覆盖
php webman typephp:package --force

# 强制使用最新 TypePHP stub 重置 main.php 入口（原有 main.php 会自动备份为 main.php.bak）
php webman typephp:package --refresh-main

默认 builder 为 tinywan/typephp-webman-builder:v0.0.17。编译在 Docker 中完成，宿主机不需要 C++、Clang 或 TypePHP 编译器。

4. 启动产物

将 dist/ 复制到兼容的 Linux x86_64/glibc 服务器，在目录内启动：

cd dist
./start.sh start

start.sh 会自动指定 PHPRC 加载随包的 php.ini，并将随包发布的 lib/ 加入动态库搜索路径。也支持 Webman 常用命令：

./start.sh start -d
./start.sh status
./start.sh stop
./start.sh restart

也可以直接通过包装脚本启动：

./webman-server start

📦 产物契约

成功构建后的完整目录结构如下（与全静态便携环境 100% 对齐）：

dist/
├── webman-server.bin       # TypePHP 生成的 ELF 原生二进制
├── webman-server           # 启动包装脚本（自动载入 php.ini 与底层动态库）
├── start.sh                # 标准 Workerman 启动脚本
├── libphp.so               # PHP 核心运行时共享库
├── libphpx.so              # PHPX 运行时共享库
├── php.ini                 # 自包含纯净 PHP 运行时配置
├── ext/                    # 随包分发的 PHP 核心与网络扩展模块 (.so)
├── lib/                    # 随包发布的底层系统与扩展动态依赖库 (ldd 完整收集)
├── runtime/                # 运行时缓存与日志目录 (logs, views)
├── build-manifest.json     # 输入、镜像与时间等构建元数据
├── config/                 # 项目运行时配置（若存在）
├── public/                 # 静态资源（若存在）
└── app/view/               # 视图模板（若存在）

lib/ 携带构建及扩展所需的所有动态依赖库；glibc、动态加载器由目标系统提供。build-manifest.json 用于追踪构建，不应写入密钥、令牌或其他敏感信息。

🛠️ 命令

⚙️ 配置

安装插件后，配置文件位于 config/plugin/tinywan/typephp/app.php：

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

构建效果

检查构建环境 php webman typephp:doctor

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]

构建二进制 php webman typephp:package

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...
[Analyzing 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