compiler/docs/en/README.md

TypePHP Compiler Internal Documentation

This directory contains compiler implementation, compatibility, build-mode, and special-topic design documents. The user-facing manual lives in the separate aot/docs repository; the research reports and refactoring plans here may describe historical state, and current behavior should be determined by the code, tests, and compatibility checklist.

Current authoritative documents

• AOT and PHP Incompatible Features Checklist: a concise list of current limitations.
• Incompatibility Classification: distinguishes Hard Limit, Intentional Rule, Pending, and Partial.
• Compiler CLI: current CLI arguments and project configuration.
• Compilation Modes: binary, extension, library modes.
• Quick Start: the minimal compile flow.
• Compile-time Functions: any(), refval(), objval(), expected(), unexpected(), and keyword methods.
• Native Types, High-Precision Types, Std Containers.
• Three Object Storage and Passing Models: the responsibilities, ABI, and non-substitutable boundaries of Zend Object, PHPX Box, and Native Class Object.
• Universal and Extension Methods, Generator.
• #[Immutable] compile-time read-only contract: methods, parameters, aliases, call boundaries, and dynamic escape rules.
• #[ArrayDef] array property contract: List/Map metadata, direct-write checks, and dynamic escape boundaries.
• Class Inheritance, Mixed C++/PHP.

Architecture and maintenance

• Backend-Neutral IR
• TypePHP WASM Technical Plan and Implementation Plan
• Building TypePHP WASI Programs
• Rebuilding the PHPX WASM Static Library: incremental rebuild of libphpx.a, numeric-dependency rebuild, and full SDK rebuild boundaries.
• Core Refactoring Plan
• Scope Management Design: responsibilities and usage boundaries of CallableScope, UserCodeScopeGuard, and FakeScopeGuard.
• Runtime Initialization and Shutdown Flow: the four-layer lifecycle of PHP, PHPX, TypePHP, and the project, covering bin/ext/lib, multi-module, and WASM.
• C++ Namespaces, Prefixes, and Symbol ABI: responsibility boundaries and conflict rules for typephp_, php::, typephp_<project>, and user callables php_.
• Zend Object Creation and Property Default Value Initialization: the gen_stub.php default property table, trigger conditions for custom create_object, execution flow, and performance boundaries.
• Native Class Object Design and Implementation Acceptance Matrix.
• PHP 8.4 Property Hook Integration Design: compile-time lowering, Zend Hook metadata, object introspection, and PHPX ABI boundaries.
• Interface Property Hook Implementation Plan: interface property contracts, compile-time variance checks, and PHP 8.4 abstract Hook metadata.
• Build Speed Research
• Optimization Priority
• High-Precision Type In-Place Operation Optimization Plan
• GMP Differences

Research and historical materials

hhvm-review.md, kphp-review.md, peachpie-review.md, phpstan-design-analysis.md, php-src-optimizer-analysis.md, and the patent drafts record comparisons and design background at the time of investigation, and do not serve as the current feature list.

Maintenance rules

1. When current compatibility changes, update INCOMPATIBLE_PHP_FEATURES.md and the classification document simultaneously.
2. All syntax and semantic limitations link uniformly to the current compatibility checklist to avoid maintaining duplicate lists.
3. Feature support should be determined by PHPT/PHPUnit regression tests.
4. Historical research documents preserve the original comparison conclusions and note the investigation date where necessary; they should not be silently rewritten to reflect the current state.