TypePHP 编译器 https://swoole.com/aot/

18 KiB

Raw Blame History

TypePHP 编译实现分析、提速方案与 mago 替代评估

生成日期：2026-08-03 适用范围：swoole/typephp v0.4.3（本仓库 D:\git\php\aot-compiler）说明：所有耗时数字均来自本仓库实际基准测试（src/ 下 139 个 PHP 文件、约 1.65 MB 源码，PHP 8.4.16 CLI；端到端对比用 302 文件合成项目，Windows + MSVC）

0. 实施状态（2026-08-03 更新）

S1（合并两次解析）与 S2（writeFile 内容比对 + 生成 .cc 增量缓存）已实施并验证。

已落地的改动

文件	改动
`src/CompilerBase.php`	新增 `parseCachedAst()` / `cloneAst()`（AST 内存缓存 + CloningVisitor 深拷贝）；`writeFile()` 增加内容比对（内容相同不覆盖，返回 bool 保持 mtime 稳定）
`src/Preprocessor.php`	`prepareFile()` 改用 `parseCachedAst()`，消除与 convert 的重复 parse
`src/Translator.php`	`doConvert()` 改用 `parseCachedAst()`；新增 `hasGeneratedObjectFileCache()` / `getGeneratedObjectCacheKey()` / `getGeneratedHeaderDependencies()` / `isGeneratedSourceFile()`；`compileFile()` 对生成的 .cc 走对象缓存；`save()`/`genExtension()` 仅在实际写入时 format

实测收益（302 文件合成项目，dry 模式，3 次取均值）

场景	基线	改动后	提升
全量构建（冷）	6011 ms	5629 ms	-6.4%
增量构建（第 3 次，不清理 build）	—	5023 ms	-16.4%（相对基线冷构建）

说明：dry 模式不包含 C++ 编译，S2 对象缓存的更大收益（跳过 g++/cl 编译）需在完整 build 场景体现；dry 耗时中固定开销（CLI 启动、YAML、符号表）占比高，稀释了 S1 的解析节省。

验证记录

parseCachedAst：同一文件 prepare+convert 各调用一次，第二次命中缓存且返回深拷贝（不共享节点、无 resolvedName 残留污染）✓
writeFile 内容比对：相同内容跳过写入，mtime 保持不变 ✓
isGeneratedSourceFile：buildDir 前缀 + .cc 扩展名判断，与 getCppFile 路径一致 ✓
PHPUnit：Entity 目录 85 测试、FileScanner 等 110 测试通过（1 个 Windows 路径分隔符既有失败与本次无关）
typephp-think（554 文件）：补丁后 prepare 通过，convert 阶段因「仓库源码类型系统比 v1095 正式版严格」（Cannot re-assign）受阻，属源码版本差异，非本次改动问题

1. 编译是如何实现的（管线剖析）

1.1 总体流程

入口为 bin/tpc.php → src/compiler.php 的 main() → src/Translator.php（继承 Preprocessor → CompilerBase）。编译是一条四阶段流水线：

┌────────────────────────────────────────────────────────────────────────┐
│ ① prepare()   扫描+解析+建符号表+依赖拓扑排序                          │
│    src/Build/SourcePipelineTrait.php::prepare()                        │
│    → 每文件: Preprocessor::prepareFile()                               │
│      parser->parse()  ←── AST 解析 #1                                 │
│      NodeTraverser(NameResolver + Visitor + 常量校验 + AttributeLower) │
│      收集 symbolDeclInFile / symbolCallInFile / classMap / funcMap     │
│    → getSortedFiles(): marcj/topsort 按文件间符号依赖拓扑排序          │
├────────────────────────────────────────────────────────────────────────┤
│ ② convert()   每文件: AST → C++ 源码                                   │
│    src/Build/SourcePipelineTrait.php::convert()                        │
│    → Translator::convertFile() → doConvert()                           │
│      loadFile() 读盘（第二次）                                        │
│      parser->parse()  ←── AST 解析 #2（同一文件解析两次！）           │
│      NodeTraverser 再次遍历（与 prepare 相同的 4 个 visitor）           │
│      逐节点翻译生成 C++（CompilerBase 4000 行核心逻辑）                │
│    → 生成 func_decl.h / data_decl.h / extension-<target>.cc            │
├────────────────────────────────────────────────────────────────────────┤
│ ③ compile()   C++ → .o（外部编译器）                                  │
│    Translator::compile()                                               │
│    → phpx misc 文件 + 生成的 .cc                                      │
│    → PCH 预编译头（PrecompiledHeaderManager，内容指纹缓存）            │
│    → Linux/macOS: pcntl fork 并行（默认 4 jobs，大文件优先调度）        │
│    → Windows: 串行（supportsPcntlParallelCompile() = false）          │
│    → phpx misc 有 .o 缓存（hasMiscObjectFileCache，命令+ABI 指纹）     │
├────────────────────────────────────────────────────────────────────────┤
│ ④ build()     链接为可执行文件 / 扩展 / 库                             │
│    Translator::build() → NativeBuilder::link()                         │
└────────────────────────────────────────────────────────────────────────┘

1.2 关键实现位置

职责	文件
四阶段编排	`src/Build/SourcePipelineTrait.php`（prepare/convert）、`src/Translator.php`（compile/build）
PHP→C++ 逐节点翻译	`src/CompilerBase.php`（4133 行，核心）
扫描/符号表/依赖排序	`src/Preprocessor.php`
编译器抽象	`src/Backend/`（CompilerBackend → GccLikeBackend → Gcc/Clang、Msvc）
平台抽象	`src/Platform/`（Linux/Macos/Windows）
并行编译调度	`src/Build/NativeBuilder.php::dispatchParallel()` + `SourceCompileQueue`
PCH 管理	`src/Build/PrecompiledHeaderManager.php`
生成物落盘	`CompilerBase::writeFile()`（无内容比对，直接覆盖）

1.3 当前已具备的优化

PCH 预编译头：phpx.h 等 8 个公共头打成 .gch，带 24 位 sha256 内容指纹缓存（PrecompiledHeaderManager）。
phpx misc 对象缓存：phpx/src/misc/*.cc 的 .o 用「编译命令 + PHP ABI」指纹缓存，避免每次全量重编 PHPX 运行时。
编译并行：Linux/macOS 用 pcntl fork 并行（-j，默认 4），且按「大文件优先占满槽位 + 小文件快速通道」调度。
编译期常量展开、字面量字符串表、--dry 只生成 C++ 等。

2. 性能瓶颈实测

2.1 基准方法

用 nikic/php-parser 5.6.1（与仓库 composer.json 一致）对 src/ 全部 139 个 PHP 文件（约 1.65 MB）做多轮测量：

parse (nikic/php-parser) ×3                1455.5 ms   → 单遍 ≈ 485 ms（3.18 MB/s）
parse + NameResolver ×3                    1797.0 ms   → 单遍 ≈ 599 ms
parse+resolve+serialize (1x)                701.1 ms
unserialize ×3                              779.8 ms   → 单遍 ≈ 260 ms
parse+resolve+prettyPrint ×3               2196.0 ms
serialized AST 体积                        47.6 MB（源码的 28.8 倍）

2.2 结论性瓶颈清单（按影响排序）

#	瓶颈	证据	影响
B1	每个 PHP 文件被解析两次	`prepareFile()`（Preprocessor.php:130）与 `doConvert()`（Translator.php:2325）各自 `parser->parse()` 一次，且各自跑一遍完整 NodeTraverser	PHP 侧最大浪费：139 文件规模下纯解析+resolve ≈ 2×599ms ≈ 1.2s 起步，大项目线性放大
B2	生成的 .cc 无增量缓存	`compileFile()` 只对 phpx misc 走 `hasMiscObjectFileCache`；用户代码生成的 `.cc` 每次全量重编	改 1 个 PHP 文件也要重编全部 .cc（C++ 编译是耗时的绝对大头）
B3	生成文件无内容比对	`CompilerBase::writeFile()` 直接 `file_put_contents` 覆盖，mtime 必然变化	即使内容相同也触发下游重新依赖判断/重编，破坏增量可能性
B4	prepare/convert 阶段完全串行	两阶段都是单进程 `foreach`	多核只用于 compile；PHP 侧解析/翻译占用的核数为 1
B5	Windows 无并行编译	`Windows::supportsPcntlParallelCompile() = false`，直接走 `compileSourceFile()` 串行	Windows 大项目编译时间 = 串行全量
B6	PCH/缓存指纹每次全量计算	`PrecompiledHeaderManager::buildFingerprint()` 每次构建都递归遍历 phpx 头文件并逐个 hash（实测 131 个头文件 ≈ 42ms，PHP 侧还有 misc 缓存同样的遍历）	每次构建的固定开销，虽不大但在累积
B7	转换阶段反复 `getType()` 字符串比较、NodeFinder 多次全树扫描（如 `findSymbolUsing`、`canOptimizeMultiReturn`）	CompilerBase/Preprocessor 中多次独立 `findInstanceOf`	每文件多次 O(N) 全树扫描，可合并为一次遍历

2.3 一个反直觉的事实

AST 序列化缓存是划算的：unserialize 单遍 260ms vs parse+resolve 599ms（快 2.3 倍），即使加上 serialize 成本（首轮 ~700ms/139 文件），二次构建纯 PHP 解析阶段也能从 ~1.2s 降到 ~260ms。但注意序列化体积膨胀 28.8 倍（47.6MB/1.65MB），对磁盘 I/O 有压力——更优做法是合并两阶段解析（见方案 S1）。

3. 提速方案（按性价比排序）

S1（P0）prepare/convert 合并为单次解析 —— 省一半 PHP 解析时间

问题：同一文件 prepare 和 convert 各 parse+traverse 一次，逻辑完全重复（visitor 列表一致）。
做法：让 prepareFile() 把 parse 好的 $stmts（NameResolver 等已跑完）挂到文件缓存（内存 array<string, array<Node>>，或按 filemtime+内容hash 落盘 build/cache/ast/），doConvert() 优先取缓存；取不到（如 --force、跨进程）才重新 parse。
收益：139 文件规模 PHP 解析从 ~1.2s → ~0.6s；大项目直接减半。
风险：低。convert 依赖的 resolvedName 等 attribute 由 NameResolver 在 traverse 时写入，缓存的是 traverse 之后的 AST，语义不变。需注意 ConstantExpressionValidationVisitor 的报错回调在 prepare 是 warning、convert 是 fatal，缓存后错误在 prepare 阶段就能暴露，行为只会更早更一致。

S2（P0）生成 .cc 的增量对象缓存 —— 编译期最大收益

做法：把 hasMiscObjectFileCache() 的机制推广到所有生成的 .cc：缓存 key = 编译命令 + PHP ABI + 生成物内容 hash（或源 PHP hash + 编译器版本）。内容未变 → 跳过 g++/clang。
配套：writeFile() 加「内容比对，相同则不落盘」逻辑（解决 B3），保证 mtime 稳定。
收益：改 1 个文件后二次构建，C++ 编译从全量变为仅差异文件；这是肉眼可感知的最大提升。
风险：中。生成 .cc 的内容由 genFunctionDeclarations/genDataDeclarations 等公共头影响——若公共头变了，所有 .cc 的 #include 语义可能变，但 .cc 内容 hash 不会变。必须把公共声明头也纳入 key（hash func_decl.h/data_decl.h/extension 文件内容），或采用「.cc 内容未变且公共头未变且 .o 存在且命令指纹未变」四条件跳过。

S3（P0）修复 PCH/缓存指纹的计算时机

buildFingerprint() 每次构建全量扫描+hash 头文件（~42ms + misc 缓存同款遍历），应改为「mtime+size 列表指纹」先行判断，内容 hash 仅在前者变化时执行。

S4（P1）prepare/convert 并行化

parse+resolve 是纯函数，可用 pcntl fork 分片解析（子进程只做 parse+serialize，父进程归并反序列化），类似已有 dispatchParallel 的模式。转换阶段因共享状态（literalStrings、classMap 等）风险高，可先只并行「解析」，翻译仍串行。

S5（P1）Windows 并行编译

两条路：(a) 给 Msvc 后端加 /MP（MSVC 原生多进程编译，单命令即可）；(b) Windows 上用 proc_open 实现多进程调度替代 pcntl。收益对 Windows 用户显著。

S6（P2）工具链层

ccache/sccache 兜底（对 C++ 编译做内容缓存，配合 S2 效果更稳）；链接器换 mold/lld；-pipe、-fno-asynchronous-unwind-tables 等编译 flag 微调。

S7（P2）单次遍历替代多次 NodeFinder

findSymbolUsing() 等每文件多次 findInstanceOf 全树扫描，可合并为一次 visit 收集函数调用/类引用/常量引用三类符号，减少 O(N) 重复。

4. AST 解析能否用 mago 替代？—— 结论：不建议（现阶段不可行）

4.1 mago 是什么

mago（carthage-software/mago）是一个 Rust 编写的 PHP 工具链：lint、format、静态分析（对标 Clippy/OXC），v1.45.0（2026-07），MIT/Apache-2.0 双许可，开发活跃。其核心是自研高性能 PHP 解析器（crate：mago-syntax 词法/语法/遍历、mago-names 名称解析），官方基准：7M 行 WordPress 静态分析 1.46s（PHPStan 55.9s）、lint 0.88s、format 0.43s。已支持 PHP 8.4 property hooks、asymmetric visibility（private(set) 等）。

4.2 为什么不能直接替代

维度	nikic/php-parser（现状）	mago	兼容性判断
语言/进程	PHP 类库，进程内对象	Rust 二进制/crate，AST 是 Rust 结构	无法在 PHP 进程中直接消费
AST 模型	AST（抽象语法树），含 attribute 机制（`resolvedName`/`namespacedName` 等存于节点属性）	CST（具体语法树，含 trivia），`mago ast --json` 是调试输出	结构不同，需要完整映射层
下游依赖	TypePHP 全库 296 处 `PhpParser\*` 引用、75 个文件；依赖 `NodeTraverser`/`NodeVisitor`/`NameResolver`/`NodeFinder`/`ConstExprEvaluator`/`PrettyPrinter`/`Modifiers` 等	无 PHP API	替换 = 重写编译器前端
名称解析	`NameResolver` 写入节点 attribute，后续代码生成大量读取	`mago-names` 输出到 Rust 侧	需要桥接层搬运
代码生成	`PrettyPrinter` 用于 stub 生成（`LibraryImportStubGenerator`、`gen_stub.php`）	无等价物	缺失
错误语义	`PhpParser\Error` + 行列号，被 `SyntaxError` 包装	错误模型不同	需要适配

核心矛盾：TypePHP 不是「解析完就丢」的 linter，而是「AST 必须留在 PHP 进程内、被 4000 行 CompilerBase 逐节点翻译」的编译器。走 mago 只有两条路，都不可行：

mago CLI → JSON AST → PHP 重建对象：JSON 序列化体积远大于源码（参考第 2 节：php-parser AST 序列化已膨胀 28.8 倍，mago CST 只多不少），反序列化 + 对象重建的 CPU/内存开销会吃掉解析省下的时间，且每文件一次进程启动（exec）成本极高；同时丢失 attribute 机制、注释/行列语义需重新映射。
PHP FFI 绑定 mago-syntax crate：需要为整个 Rust AST 写 FFI 边界 + 转 PHP 对象层，工程量接近重写前端，且 mago 的 CST 与 TypePHP 需要的「带 resolvedName 的 AST」不是一回事，仍要在 PHP 侧自建名称解析与代码生成数据模型。

4.3 mago 在本项目中的合理定位（可选）

前置快速语法校验：编译前用 mago（或 mago lint --quick）做廉价的全项目语法/明显错误预检，给出比 php-parser 更快的反馈（适合 IDE/CI 场景，不进入编译流水线核心）。
性能参照物：mago 证明了「Rust 原生解析」的量级（~百 MB/s vs php-parser 3 MB/s），可作为未来「把前端重写为原生编译器（如 Rust 侧做 parse+name-resolution，产物是自研序列化 AST）」的路线参考——但那是一个全新项目，而非对现有编译器的增量改造。
若仍想引入原生解析：更现实的是保留 php-parser 语义、仅加速解析环节（如 --php-parser 的 PhpParser\ParserFactory 换用 tree-sitter 绑定并在 PHP 侧重建 php-parser 节点），但收益-成本比仍不如 S1/S2。

4.4 结论

不建议用 mago 替换 nikic/php-parser。mago 是「解析即弃」的工具链，TypePHP 是「解析后深度消费 AST」的编译器，二者 AST 模型与进程模型不兼容，桥接成本会抹平解析速度优势。真正的提速路径在 S1（两阶段合并单次解析）+ S2（生成 .cc 增量缓存 + writeFile 内容比对）+ S4/S5（并行化），全部基于现有架构增量改造，风险可控、收益立竿见影。

5. 落地顺序建议

第一阶段（P0，改动小收益大，1-2 天）
  1. writeFile 内容比对（S2 前置）
  2. prepare/convert 共享 AST（S1）
  3. 生成 .cc 增量对象缓存（S2，key 含公共头内容 hash）
第二阶段（P1，结构性收益）
  4. PCH/misc 指纹轻量化（S3）
  5. 解析阶段 pcntl 并行（S4 解析部分）
  6. Windows 并行（/MP 或 proc_open）（S5）
第三阶段（P2，长期）
  7. 单次遍历合并 NodeFinder（S7）
  8. ccache / mold / lld（S6）

6. 附：基准脚本

分析所用基准脚本：.workbuddy/bench_ast.php（可重复运行：php .workbuddy/bench_ast.php），复现本节所有数字。

18 KiB Raw Blame History