Lorenzo Dessimoni
17 hours ago
parent
a70a0ad078
commit
a8f7c29ea0
3 changed files with 196 additions and 5 deletions
@ -0,0 +1,190 @@ |
||||
# AOT/PHP Incompatibility List |
||||
|
||||
This document lists only the key areas in which the current AOT compiler is |
||||
incompatible with or more restrictive than standard PHP. |
||||
|
||||
## Program structure |
||||
|
||||
- Executable statements are not allowed at global scope; only static constructs |
||||
such as declarations, `use`, `declare`, and constant definitions are allowed. |
||||
- Function declarations are not allowed inside functions or methods. |
||||
- Named class declarations are not allowed inside functions or methods. |
||||
- Binary mode must define a global `main()`. |
||||
- `main()` may either take no parameters or have the signature |
||||
`(int $argc, array $argv)`. |
||||
- `main()` must return `void`. |
||||
|
||||
## Declarations and types |
||||
|
||||
- Variable variables `$$var` are not supported. |
||||
- PHP 8.5 `#[NoDiscard]` is not supported yet. |
||||
- The PHP 8.5 `(void)` cast is supported for explicitly discarding a value; the |
||||
operand is still evaluated and its side effects are preserved, and the cast |
||||
cannot be used in value contexts such as assignments, returns, arguments, or |
||||
conditions. |
||||
- Support for PHP 8.5 `clone()` / clone-with requires the linked `libphp` to be |
||||
version 8.5 or later. Public and dynamic properties, private/protected/readonly |
||||
properties, property hooks, call ordering, error propagation, and callable |
||||
paths are all covered by PHPT tests. |
||||
- PHP 8.4 property hooks are compiled into AOT getters/setters and register the |
||||
corresponding Zend hook metadata; direct property reads/writes, Reflection, |
||||
and object iteration are all supported. Taking a reference to a hooked |
||||
property is currently not supported. |
||||
- PHP 8.4 Reflection Lazy Objects cannot be used with TypePHP AOT classes. AOT |
||||
classes are registered as persistent internal classes, and Zend's |
||||
`zend_object_make_lazy()` explicitly rejects internal classes. Zend PHP user |
||||
classes loaded dynamically at runtime are not subject to this restriction. |
||||
- `private(set)` and `protected(set)` asymmetric property visibility is |
||||
supported, including constructor property promotion. Zend-backed objects |
||||
perform the scope check through the PHP 8.4+ class-level object handler and |
||||
preserve the promoted / set-visibility / implicit-final reflection flags; |
||||
Native objects enforce the equivalent scope rules through compile-time access |
||||
checks. |
||||
- Final properties declared through constructor promotion are supported, but |
||||
TypePHP requires an explicit `public`, `protected`, or `private` modifier; |
||||
PHP 8.5's implicitly public form, `final int $value`, is not accepted. As a |
||||
TypePHP extension, this syntax is independent of the PHP source-syntax version |
||||
supported by the linked `libphp` and remains available when using a PHP 8.4 |
||||
`libphp.so`. |
||||
- TypePHP forbids attributes on global or namespaced constant declarations; PHP |
||||
8.5 global constant attributes are out of scope. Class constant attributes are |
||||
not affected by this restriction. |
||||
- Returning by reference from closures or arrow functions is not supported. |
||||
- PHP 8.5 `static function` expressions in global constants, class constants, |
||||
parameter defaults, or property defaults are not supported yet. Closures |
||||
nested inside initializer expressions are likewise rejected at compile time. |
||||
- `__construct()` may not have a return value. |
||||
- A parameter with a default value may not appear before a required parameter |
||||
(PHP permits this legacy pattern but treats the former parameter as required). |
||||
- Variadic parameters by reference `&...$args` are not supported. |
||||
- Union, intersection, and nullable types are still represented as `mixed/any` |
||||
in C++, but the static analysis phase uses known expression types to reject |
||||
definitely incompatible arguments, return values, and property assignments |
||||
ahead of time; dynamic values still retain their runtime type checks. |
||||
- Once a local variable's type has been statically inferred as a concrete native |
||||
type, reassigning it to an incompatible type within the same scope is not |
||||
supported. |
||||
|
||||
## declare |
||||
|
||||
- `declare(ticks=...)` is not supported. |
||||
- `declare(encoding=...)` accepts only `UTF-8`. |
||||
- `declare(strict_types=...)` accepts only `strict_types=1`. |
||||
- No other `declare` directives are supported. |
||||
|
||||
## Calls and references |
||||
|
||||
- `exit(message: $value)` is available as a TypePHP named-argument extension; it |
||||
enters the same exit path as the positional form `exit($value)`. |
||||
- TypePHP uses strict argument-count rules: non-variadic functions do not accept |
||||
extra arguments beyond the declared signature, and `func_get_args()` does not |
||||
implicitly relax the signature. |
||||
- Reference parameters and write-back semantics are supported for ordinary |
||||
functions, ordinary methods, and native direct calls with known signatures; |
||||
do not mistakenly describe the compiler's internal cross-trait dynamic-dispatch |
||||
limitation as "TypePHP does not support reference parameters". |
||||
- Closures and arrow functions do not support reference parameters. |
||||
- Reference assignment cannot create a reference from a complex static-property |
||||
expression. |
||||
- Calls whose argument signature cannot be determined at compile time — dynamic |
||||
calls, closure calls, and the like — cannot convert reference parameters |
||||
automatically; `refval()` or the equivalent keyword method `toRef()` must be |
||||
used explicitly. |
||||
- `refval()` / `toRef()` only accept variables, array elements, or object |
||||
properties. |
||||
- A call that uses argument unpacking followed by named arguments falls back to |
||||
dynamic dispatch and cannot use the native call path. |
||||
|
||||
## Object model |
||||
|
||||
- Reserved keyword methods such as `toInt()`, `toString()`, and `toArray()` are |
||||
resolved before ordinary object methods; an application method of the same |
||||
name that takes arguments is not called with ordinary object-method semantics. |
||||
- `toAny()` and `toRef()` are non-overridable TypePHP keyword methods, and |
||||
ordinary class-like declarations must not define methods with these names |
||||
(method names are case-insensitive, per PHP rules). A Native class may only |
||||
explicitly define a `toAny()` conversion method returning `mixed/any`; no |
||||
implicit conversion is provided. Native classes do not support `toRef()`. |
||||
- Fixed-layout typed properties that are not explicitly initialized use the |
||||
zero value of their type and do not preserve Zend PHP's full uninitialized |
||||
state; expressions such as `??` that depend on the uninitialized state may |
||||
therefore behave differently. |
||||
- A subclass may not shadow a parent's private property with a `private` |
||||
property of the same name; `public` / `protected` declarations of the same name |
||||
are treated as the same inherited property slot and must still satisfy the |
||||
type, visibility, and `readonly` compatibility requirements. |
||||
- To avoid introducing extra dynamic checks in the typed-property write path, a |
||||
native typed property falls back to `setProperty()` when the right-hand side's |
||||
type is unknown or inconsistent with the property type; some scalar |
||||
assignments may then follow Zend's weak type conversion instead of the AOT |
||||
default strict semantics. |
||||
|
||||
## Expressions and control flow |
||||
|
||||
- A `match` arm condition may not itself be a `match` expression. |
||||
- The value target in a by-reference `foreach` may only be a variable. |
||||
- `foreach` list destructuring does not support binding elements by reference. |
||||
- Appending, inserting, `unset()`, and wholesale replacement of `std::vector`, |
||||
`std::map`, and `std::ordered_map` are forbidden during a `foreach`; |
||||
non-structural updates of existing elements can still be done with assignment |
||||
operators. |
||||
- Fixed native typed object properties cannot be freely `unset()` with PHP's |
||||
standard uninitialized-property semantics. |
||||
- Calling `unset()` on a native-typed variable does not delete the variable as |
||||
it would in standard PHP. |
||||
|
||||
## Runtime dynamic capabilities |
||||
|
||||
- `ClassName::class` only supports string literals or statically resolvable |
||||
class names. |
||||
- `static::class` is not supported in positions that require a compile-time |
||||
constant class name. |
||||
- `__CLASS__` may only be used within a `class` definition (PHP allows |
||||
it elsewhere and returns an empty string). |
||||
- `__TRAIT__` may only be used within a `trait` definition (PHP allows |
||||
it elsewhere and returns an empty string). |
||||
- Dynamic property chains, dynamic class names, dynamic function names, and |
||||
dynamic callbacks all go through the Zend runtime fallback and are not |
||||
guaranteed to be natively optimized; reference parameters of dynamic calls |
||||
still require an explicit `refval()` or `toRef()`. |
||||
- When `Closure::bind()` binds a static closure that accesses private members, |
||||
the current behavior is not fully consistent with standard PHP. |
||||
- Storing a first-class callable in a nullable typed `Closure` property |
||||
currently has runtime stability limitations. |
||||
- All source files must be encoded as `UTF-8`. |
||||
|
||||
## Compiler bootstrapping and internal refactoring constraints |
||||
|
||||
This section describes the constraints that apply when the compiler itself is |
||||
compiled with TypePHP. These are not additional PHP semantic differences for |
||||
user code. |
||||
|
||||
- Before the refactoring, a statically resolvable `$this->method()` call within |
||||
the same core class generated a native C++ direct call. Reference parameters |
||||
were mapped directly to `php::Ref` or a C++ reference, and write-back |
||||
semantics worked normally. |
||||
- After splitting the caller and callee into different traits, compiling the |
||||
trait body on its own makes it impossible to determine the final host class |
||||
from the trait's `$this`. The current method resolver may lower a cross-trait |
||||
call to a Zend method call, for example generating |
||||
`this_.call(..., php::ArgList{value})`. |
||||
- The `ArgList` of a dynamic method call does not automatically promote ordinary |
||||
arguments to references based solely on the callee wrapper's arginfo. If the |
||||
callee method declares `&$value`, the wrapper fetches the argument through |
||||
`getCallArgByRef()`, while the caller passes an ordinary value; the result is a |
||||
`must be passed by reference` warning, and modifications made by the callee |
||||
cannot be written back to the caller. |
||||
- Therefore, cross-trait APIs inside the compiler must not use reference output |
||||
parameters or a protocol in which a passed scalar or array is modified and |
||||
then read by the caller. They should return a result value, a tuple array, or |
||||
a DTO — for example, use `[$type, $class] = resolveTypeDecl(...)` instead of |
||||
`parseTypeDecl(..., &$class)`. |
||||
- Internal helpers for string accumulation, array sorting, parse-result output, |
||||
and the like should preferably be designed around pure return values: |
||||
`$code .= format(...)`, `$files = sort(...)`. Only when the call is confirmed |
||||
to stay a native direct call may reference write-back be relied upon. |
||||
- Every time a method is moved to a trait, a parent class, or a separate |
||||
component, at least one test covering that call must be recompiled with the |
||||
bootstrapped artifact; running tests only with `bin/tpc.php` cannot reveal |
||||
problems where "the source compiler works but the bootstrapped compiler |
||||
regresses". |
||||
Loading…
Reference in new issue