AOT 与 PHP 不兼容特性清单

本文档只记录当前 AOT 编译器与标准 PHP 不兼容或受限的关键特性。

程序结构

全局作用域不允许可执行语句；只允许声明、use、declare、常量定义等静态结构。
函数和方法内部不允许声明函数。
函数和方法内部不允许声明具名类。
二进制模式必须定义全局 main()。
main() 只允许无参数，或 (int $argc, array $argv)。
main() 必须返回 void。

声明与类型

不支持可变变量 $$var。
暂不支持 PHP 8.5 #[NoDiscard]。
支持 PHP 8.5 (void) 显式丢弃语句；操作数仍会求值并保留副作用，不能在赋值、返回、参数或条件等值上下文中使用。
PHP 8.5 clone() / clone-with 依赖实际链接的 libphp 版本不低于 8.5。公开、动态、private/protected/readonly 和 property hook 属性，以及调用顺序、错误传播和 callable 路径均有 PHPT 覆盖。
PHP 8.4 property hooks 会编译为 AOT getter/setter，并注册对应的 Zend hook 元数据；直接属性读写、Reflection 和对象遍历均受支持。当前不支持对 hook 属性取引用。
Interface property hook 暂不支持为 set 显式声明参数；应使用隐式的 setter value 参数。
PHP 8.4 Reflection Lazy Object 不能用于 TypePHP AOT 类。AOT 类以 persistent internal class 注册，而 Zend 的 zend_object_make_lazy() 明确拒绝 internal class；运行时动态加载的 ZendPHP user class 不受此限制。
支持 private(set) 与 protected(set) 非对称属性可见性，包括 constructor property promotion；Zend-backed 对象通过 PHP 8.4+ 类级 object handler 执行作用域检查，并保留 promoted/set visibility/implicit final 反射标志；Native 对象通过编译期访问检查执行同等作用域规则。
支持 final constructor property promotion，但 TypePHP 要求同时显式声明 public、protected 或 private；不接受 PHP 8.5 的 final int $value 隐式 public promotion 写法。该语法作为 TypePHP 扩展不受所链接 libphp 的源码语法版本限制，使用 PHP 8.4 libphp.so 时仍然可用。
TypePHP 禁止在全局或命名空间常量声明上使用 attributes；PHP 8.5 global constant attributes 不在支持范围内。class constant attributes 不受此限制。
.stub.php 只声明由外部 C++ 提供的 Zend ABI 符号，禁止对其中的类使用 #[Native]；Native Class 的对象布局必须由 TypePHP 编译器生成并持有。
不支持闭包或箭头函数按引用返回。
暂不支持 PHP 8.5 在全局常量、类常量、参数默认值或属性默认值中使用 static function；初始化表达式内嵌套的闭包同样会在编译期被拒绝。
__construct() 不允许返回值。
参数默认值不允许出现在必填参数之前（PHP允许，但会直接丢弃此默认参数）。
不支持引用可变参数 &...$args。
联合类型、交叉类型、nullable 类型仍以 mixed/any 作为 C++ 表示，但静态阶段会利用已知表达式类型提前拒绝确定不兼容的参数、返回值和属性赋值；动态值仍保留运行时 type check。
局部变量类型一旦被静态推断为具体 native 类型，不支持在同一作用域内重新赋值为不兼容类型。

declare

不支持 declare(ticks=...)。
declare(encoding=...) 只允许 UTF-8。
declare(strict_types=...) 只允许 strict_types=1。
不支持其他 declare 指令。

调用与引用

exit(message: $value) 可作为 TypePHP named-argument 扩展使用；它与位置参数 exit($value) 进入同一退出路径。
TypePHP 使用严格参数数量规则：非 variadic 函数不接受声明范围之外的额外参数；func_get_args() 不会隐式放宽签名。
已知签名的普通函数、普通方法和 native 直调支持引用参数及写回；不要把编译器内部跨 Trait 动态分派的限制误写成“TypePHP 不支持引用参数”。
闭包和箭头函数不支持引用参数。
引用赋值不支持从复杂静态属性表达式建立引用。
动态调用、闭包调用等编译期无法确定参数签名的调用，不能自动转换引用参数；需要显式使用 refval() 或等价关键词方法 toRef()。
refval() / toRef() 只接受变量、数组元素或对象属性。
带 unpack 且尾部追加 named arguments 的调用会退化为动态调用，不能使用 native call。

对象模型

toInt()、toString()、toArray() 等保留关键词方法先于普通对象方法解析；需要参数的同名业务方法不按普通对象方法语义调用。
toAny() 和 toRef() 是不可覆盖的 TypePHP 关键词方法，普通 class-like 声明不得定义同名方法（方法名按 PHP 规则大小写不敏感）。Native class 仅可显式定义返回 mixed/any 的 toAny() 转换方法，不提供隐式转换；Native class 不支持 toRef()。
固定值类型属性未显式初始化时使用类型零值，不保留 ZendPHP 的完整 uninitialized 状态；因此 ?? 等依赖 uninitialized 状态的表达式可能不同。
禁止子类用同名 private 属性隐藏父类私有属性；public / protected 同名声明视为同一个继承 property slot，仍须满足类型、可见性和 readonly 兼容性要求。
typed property 的动态写入路径仍执行 strict type check；右值类型在编译期无法确定时会保留运行时检查，而不会退化为 Zend 弱类型标量转换。
Native Class 使用独立的固定布局对象模型，不能被当作普通 Zend Object、PHP array key/value 或任意 mixed 值使用，并限制动态成员、引用、static/readonly 成员及部分操作符。完整边界参见 Native Class Object 设计。

表达式与控制流

match 的 arm condition 不能是 match 表达式。
foreach by reference 的 value 只能是变量。
foreach list destructuring 不支持按引用绑定元素。
非 int/bool lowering 路径中的非空 switch case 必须以 return、break、continue、exit 或 throw 结束；不要依赖 PHP 的隐式 case fallthrough。当前 int/bool native switch 路径仍可保留 C++ fallthrough，因此项目代码应统一显式终止每个非空 case。
std::vector、std::map、std::ordered_map 在 foreach 期间禁止追加、插入、unset() 或整体替换；已有元素的非结构性更新仍可使用赋值运算符完成。
固定 native typed object property 不允许按 PHP 未初始化语义自由 unset()。
native 类型变量执行 unset() 不会产生标准 PHP 的变量删除语义。

运行时动态能力

普通 Zend 对象和动态类表达式支持运行时 ::class 与 class constant lookup；Native Class 仍要求相关类目标能够在编译期确定。
static::class 在需要编译期常量类名的位置不支持。
__CLASS__ 只允许在 class 定义的代码段中使用（PHP允许，返回空字符串）。
__TRAIT__ 只允许在 trait 定义的代码段中使用（PHP允许，返回空字符串）。
动态属性链、动态类名、动态函数名和动态回调会统一走 Zend runtime fallback，不保证 native 优化；动态调用的引用参数仍需显式使用 refval() 或 toRef()。
不支持 Closure::bind()、Closure::bindTo() 和 Closure::call()；闭包不能在 AOT 代码中重新绑定对象或 class scope。
所有源文件必须是 UTF-8 编码。

Generator

TypePHP generator 使用 FiberGenerator 而不是 Zend Generator，因此不能依赖 instanceof Generator、ReflectionGenerator、Zend Generator 的内部对象布局或完全相同的异常栈。Generator 不支持按引用返回、by-reference yield、按引用 foreach、引用参数或 variadic 参数；WASI target 暂不支持 Fiber 和 Generator。完整边界参见 Generator。

7.9 KiB Raw Blame History