Copilot instructions for this repository

Project overview

TypePHP is a PHP native compilation project. Its tpc command is TypePHP Compiler (AOT), which translates PHP source into C++, then compiles and links it into a native binary or a PHP extension. The primary entrypoint boots src/compiler.php; that drives TypePhp\Translator through a fixed pipeline:

prepare() scans files, parses ASTs, collects symbols, and topologically sorts PHP files by cross-file symbol usage.
convert() turns PHP ASTs into generated .cc files while passing through native source files (.cpp, .c, .s, .m, .mm).
compile() chooses the platform/compiler backend, generates support sources and headers, and compiles sources, using pcntl parallelism when available.
build() links object files into the final executable or extension.

src/CompilerBase.php contains most PHP-to-C++ translation logic and mixes in many traits for syntax handling and optimizations. src/Preprocessor.php owns dependency discovery and file ordering. Platform-specific behavior lives under src/Platform/, compiler backends under src/Backend/, and metadata/state objects under src/Entity/ and src/Context/.

Setup and build commands

The repo expects PHP 8.4+, GCC 9+ with C++17, CMake 3.24+, and a compiled swoole/phpx dependency. Install PHP dependencies with:

composer install

Build phpx before relying on compiler runs:

cd vendor/swoole/phpx
cmake .
make -j32

Compile a project, directory, single file, or project.yml:

./tpc <path-to-project-or-file>
./tpc <path> -O2
./tpc <path> --mode=ext -o <output_name>

Test commands

Run the PHPUnit suite:

./vendor/bin/phpunit

Run a single PHPUnit file or a single test method:

./vendor/bin/phpunit phpunit/src/Platform/PlatformTest.php
./vendor/bin/phpunit --filter testWindowsBasic phpunit/src/Platform/PlatformTest.php

Run PHPT integration tests:

php run-tests.php tests/compiler/
php run-tests.php tests/compiler/arrays.phpt

For parser/runtime comparison without AOT compilation, there are docs using:

php run-tests.php --no-aot tests/compiler/arrow-functions.phpt

Formatting

The repo ships a PHP CS Fixer config in .php-cs-fixer.dist.php:

php vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php <path>

Generated C++ is auto-formatted by the compiler itself when clang-format is available.

Configuration and repository conventions

project.yml is the project-level build config. Important keys include name, build-mode, cxx-std, cxx-flags, ld-flags, sources, ignore, and resource.
Command-line options intentionally override YAML values. Translator parses YAML first, then applies CLI arguments last.
YAML parsing accepts both hyphenated and underscored variants for several keys, but existing examples use hyphenated names such as build-mode and cxx-std.
In bin mode, compiled programs must define main(). In ext mode they do not.
File discovery is mixed-language by design: PHP is translated, while native sources are compiled directly if they appear in configured sources.
Generated files are written under build/, with generated C++ paths mirroring the source tree and generated headers under build/include/.
Platform/compiler selection is centralized: PlatformFactory detects the OS, and CompilerFactory picks the backend (Gcc, Clang, Msvc) with environment/config overrides.

Test-specific conventions

PHPUnit tests for compiler internals should use CompilerTest::create(ROOT_PATH), which enables test mode instead of normal fatal exits.
phpunit/bootstrap.php exposes a BaseTest::exec() helper that expects compilation failures to surface as TypePhp\Exception\TestError.
PHPT end-to-end tests live in tests/compiler/; existing guidance and examples generally put executable test logic inside a main() function.

3.9 KiB Raw Blame History