compiler/docs/README.md

TypePHP 编译器内部文档

本目录包含编译器实现、兼容性、构建模式和专项设计文档。用户侧使用手册位于独立的 aot/docs 仓库；这里的研究报告和重构计划可能描述历史状态，当前行为应以代码、测试和兼容性清单为准。

当前权威文档

• AOT 与 PHP 不兼容特性清单：当前限制的简明清单。
• 不兼容性分类：区分 Hard Limit、Intentional Rule、Pending 和 Partial。
• 编译器命令行：当前 CLI 参数和项目配置。
• 编译模式：binary、extension、library 模式。
• 快速入门：最小编译流程。
• 编译期函数：any()、refval()、objval()、expected()、unexpected() 和关键词方法。
• 原生类型、高精度类型、Std 容器。
• 三套对象存储与传递模型：Zend Object、PHPX Box 与 Native Class Object 的职责、ABI 和不可替代边界。
• 通用与扩展方法、Generator。
• #[Immutable] 编译期只读契约：方法、参数、别名、调用边界与动态逃逸规则。
• #[ArrayDef] 数组属性契约：List/Map 元数据、直接写入检查与动态逃逸边界。
• 类继承、混合 C++/PHP。

架构与维护

• 后端中立 IR
• TypePHP WASM 技术方案与实施计划
• 构建 TypePHP WASI 程序
• 重建 PHPX WASM 静态库：增量重编 libphpx.a、数值依赖重建与完整 SDK 重建边界。
• 核心重构计划
• 作用域管理设计：CallableScope、UserCodeScopeGuard 与 FakeScopeGuard 的职责和使用边界。
• Native Class Object 设计 与 实现验收矩阵。
• PHP 8.4 Property Hook 集成设计：编译期 lowering、Zend Hook 元数据、对象内省及 PHPX ABI 边界。
• Interface Property Hook 实现方案：接口属性契约、编译期方差检查及 PHP 8.4 抽象 Hook 元数据。
• 构建速度研究
• 优化优先级
• 高精度类型原地运算优化方案
• GMP 差异

研究与历史资料

hhvm-review.md、kphp-review.md、peachpie-review.md、phpstan-design-analysis.md、php-src-optimizer-analysis.md 以及专利草案用于记录调研时点的比较和设计背景，不作为当前功能清单。

维护规则

1. 当前兼容性变化同时更新 INCOMPATIBLE_PHP_FEATURES.md 和分类文档。
2. 所有语法和语义限制统一链接到当前兼容性清单，避免维护重复清单。
3. 功能是否支持应以 PHPT/PHPUnit 回归测试为依据。
4. 历史研究文档保留原始比较结论，并在需要时注明调研日期，不应悄然改写为当前状态。