hyperf-typephp-aot

Hyperf 项目使用 TypePHP（Swoole 出品的 PHP AOT 编译器）编译为原生二进制的完整适配方案与实战规范。

把 Hyperf 应用编译成单个可执行文件：业务 PHP 代码翻译成 C++ 编入二进制，vendor/config 由内置 Zend 运行时动态加载。产物拷走即跑；开启全静态链接（musl）后更是零依赖——目标机器连 PHP 都不用装，Alpine、Debian、任意 glibc 版本通吃。

本仓库沉淀自一个真实上线的 Hyperf 3.2 生产项目（PHP 8.4/8.5 双版本工具链验证）的完整适配过程，包含：

• 代码红线清单——哪些 PHP 写法 TypePHP 编译不了，怎么改（含官方已修/未修 bug 对照）
• 框架机制冲突的标准解法——#[Inject] 属性注入、__DIR__ 固化、代理类、Model 继承链等
• 一键构建脚本——代理生成 → 动态 yml → 编译 → 组包 → 打补丁，全自动
• 全静态编译指南——用 swoole-cli SDK 实现零依赖分发
• 真实案例台账——一个 Hyperf 项目从零到编译通过、空容器分发实测的完整记录

目录

文件	说明
SKILL.md	核心规范文档。可直接作为 AI Agent Skill 使用（见下文）
build-dist.sh	一键编译组包脚本模板（代理接管、yml 动态重写、组包、补丁全自动）
typephp.yml	编译配置模板（sources/ignore 组织规则见 SKILL.md）
docs/case-study.md	实战案例：某生产项目的适配台账与踩坑记录

快速上手

前置条件：

• TypePHP 编译器与工具链（按其官方文档安装）
• Hyperf 3.x 项目
• 全静态编译另需：clang + swoole-cli SDK（构建方法见 docs/case-study.md）

步骤（详细版见 SKILL.md 的迁移 checklist）：

# 1. 把模板放进你的 Hyperf 项目根目录
cp build-dist.sh typephp.yml /path/to/your-hyperf-project/

# 2. 按 SKILL.md 第一节红线检查/修改代码写法（编译器报错是最准的扫描器）

# 3. 一键编译 + 组包（默认全静态）
cd /path/to/your-hyperf-project
./build-dist.sh

# 4. 产物 build/dist/ 整个目录拷走即可运行
./build/dist/start.sh

作为 AI Agent Skill 使用

本仓库就是一个现成的 Agent Skill（Claude Code / Kimi Code 等通用）：

git clone https://github.com/xiaoyin199/hyperf-typephp-aot.git ~/.agents/skills/hyperf-typephp-aot

之后让 AI 帮你做 Hyperf 项目的 TypePHP 适配时，它会自动遵循 SKILL.md 里的红线、解法与验收标准（包括「空容器实测才算分发成功」这类硬规矩）。

关键经验速览

• #[Inject] 属性注入在 AOT 下静默失效 → 代理类参与编译接管（脚本已自动化，新增注入类零配置）
• __DIR__/__FILE__ 在编译期固化为开发机绝对路径 → 运行期资源一律 BASE_PATH 定位
• func_get_args() 隐式接参、参数重赋值类型变化、给无参方法传参 → 改写或进 ignore
• swoole.use_shortname 是 PHP_INI_SYSTEM（swoole ≥6.2.2 默认变回 On）→ dist 必须带 php.ini + PHPRC
• 分发验收必须空容器实测（alpine + 挂载 dist）——宿主机自测发现不了路径固化类问题

适用版本

• TypePHP 0.6.8+ / master（部分官方 bug 修复需要新版，见 docs 案例的 issue 状态表）
• Hyperf 3.1/3.2
• PHP 8.3 / 8.4 / 8.5（全静态产物的 PHP 版本由 SDK 决定）

License

MIT