compiler/docs/en/INCOMPATIBLE_PHP_FEATURES.md

# 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".