Compile PHP to Native Binaries

English | 简体中文

TypePHP is an Ahead-Of-Time (AOT) compiler that translates PHP source code into C++ and then into native machine code. Unlike a bytecode cache or a VM, it does not interpret opcodes at runtime: it generates optimized native binaries that run directly on the CPU.

It keeps familiar PHP syntax and adds compile-time type information, so the compiler can emit fast, statically-typed C++ for hot paths. Dynamic PHP values, internal functions, reflection, and object metadata continue to interoperate with the Zend runtime through PHPX; user functions are not executed as Zend opcodes after they have been compiled.

TypePHP is written entirely in PHP and is fully self-hosting: the tpc compiler binary is built by compiling the compiler's own PHP source code with TypePHP. The bootstrap chain is pure PHP — no C or C++ glue in the compiler itself.

TypePHP is under active development. It intentionally supports a defined, testable subset of PHP rather than claiming drop-in compatibility with every dynamic PHP program. Read Compatibility model and the incompatible-feature list before adopting it for an existing application.

PHP source + .stub.php declarations + optional C/C++ sources
                         │
                         ▼
        parse, validate, and collect declarations
                         │
                         ▼
       lower function bodies and constants to C++17
                         │
                         ▼
       native compiler + reusable object/PCH caches
                         │
                         ▼
 executable | PHP extension | shared library | WASI component

The prepare phase builds the complete symbol model without allocating runtime cache IDs. Constants and declaration defaults retain their AST until the convert phase, where they are lowered after all project symbols are known. This two-phase design keeps multi-file and self-hosted builds deterministic.

• Self-hosting, written in PHP — the TypePHP compiler is implemented entirely in PHP and bootstraps itself: tpc compiles the compiler's own source into a native binary.
• True AOT compilation — PHP is lowered to C++17, then to native machine code. No interpreter, no opcode cache, no JIT warm-up.
• Three native build modes — build a native bin executable, a loadable PHP ext extension, or a reusable lib shared library from the same codebase.
• Native type system — int, float, and bool map directly to C++ scalar types (int64_t, double, bool) for orders-of-magnitude speedups on numeric code.
• High-precision numerics — bigInt (GMP), decimal (libmpdec), and bigFloat (MPFR), with typed operators and method APIs.
• Strongly-typed containers — std::array, std::vector, std::map, and std::ordered_map with compile-time element types; up to 10× faster than PHP arrays and on par with C++ std::vector.
• Universal methods — call methods directly on primitives ($s->upper(), $arr->contains(), $big->mul(2)); statically-known calls are resolved directly at compile time.
• Mixed C++ / PHP — call C++ functions from PHP (and vice versa) for performance-critical kernels.
• Compile-time functions & keywords — any(), refval(), objval(), expected(), unexpected(), plus toInt(), toString(), toArray() and friends.
• Compile-time safety — #[Immutable] read-only contracts and #[ArrayDef] array-shape metadata, checked at compile time with zero runtime cost.
• Compile-time code generation — #[Getter], #[Setter], #[With], #[Constructor], #[Printer], and #[Arrayable] generate type-safe methods from property declarations.
• Modern PHP support — PHP 8.4 property hooks, asymmetric visibility, PHP 8.5 clone()-with, and (void) discard expressions.
• Cross-platform & WASM — Linux, Windows, and macOS targets for x64 and ARM64, plus WASI 0.2 and browser (Jco) output.
• Python bridge — generate IDE helpers for Python modules and convert Python scripts to TypePHP.

Strengths over plain PHP:

• Near-native performance. Numeric and container-heavy hot paths compile down to the same machine code a C++ program would produce. See the benchmark below.
• Source protection. Your source is compiled away — shipped artifacts are native binaries, not readable PHP files.
• Native process entry. Binary mode starts directly from a native executable and does not require the PHP CLI or a separate interpreter process. The executable still embeds/links PHPX, libphp, and any configured native libraries, which must be available in the deployment package.
• Gradual typing that actually pays off. Add use native_types, std:: containers, and type declarations only where performance matters; the rest stays ordinary PHP.
• Zend ecosystem interop. Extension mode loads as a standard PHP extension, and projects can call supported internal functions and require other Zend extensions explicitly.

• PHP 8.4 – 8.5 CLI, development headers, and php-config
• The matching PHP embed library (libphp.so or libphp.dylib) for binary/shared-library builds on Unix-like systems
• GCC 9+ (or Clang) with C++17
• CMake 3.24+
• Composer 2
• High-precision math libraries: GMP, MPFR (libmpdec is bundled with PHPX)

# Ubuntu/Debian
sudo apt install build-essential cmake pkg-config libgmp-dev libmpfr-dev

# RHEL/CentOS/Fedora
sudo dnf install gcc gcc-c++ cmake pkgconf-pkg-config gmp-devel mpfr-devel

# Arch Linux
sudo pacman -S base-devel cmake pkgconf gmp mpfr

GMP powers bigInt and MPFR powers bigFloat. The decimal type is backed by libmpdec, which is bundled with PHPX — no separate install required.

Linux x64 is the primary development and full-test CI platform. The compiler also has Windows, macOS, ARM64, and WASI backends; availability of PHP embed, toolchain, and third-party libraries still determines which target can be built on a given host.

Native release assets are built with the latest PHP 8.5 ZTS release. TypePHP publishes Linux x64, Linux ARM64, macOS ARM64, and Windows x64 packages. Native NTS and 32-bit x86 packages are not provided. Linux and macOS archives contain the compiler and production Composer dependencies, while the Windows archive contains the complete matching PHP/PHPX runtime and SDK.

composer require --dev swoole/typephp

Then compile your project:

vendor/bin/tpc.php project.yml

When working inside the TypePHP source repository, use the local entry point instead:

bin/tpc.php project.yml

git clone https://github.com/swoole/typephp.git
cd typephp
composer install
php bin/tpc.php --help

PHPX_HOME may point to a separate PHPX checkout or installation. PHP_HOME may point to the PHP embed prefix; it must contain bin/php-config, PHP headers, and lib/libphp.so on Unix-like systems.

Binary and shared-library builds require PHP's embed SAPI. If libphp.so is missing on Linux, tpc.php can interactively download the PHP source and build it for you. A PHP extension build resolves Zend symbols from the host SAPI and must not load a second libphp. See Automatic libphp.so build.

Create hello.php:

<?php

function main(): void
{
    echo "Hello World!\n";
    var_dump(PHP_VERSION);
    var_dump(php_uname());
}

Compile and run it:

bin/tpc.php hello.php
./hello

Example output (the exact PHP version and platform strings depend on the linked runtime):

Hello World!
string(5) "8.x.x"
string(16) "Linux ..."

Binary mode requires a global main() function. It may be declared with no parameters, or as main(int $argc, array $argv) to receive command-line arguments, and must return void. Top-level executable statements are not allowed; executable code belongs in a function or method.

TypePHP supports three build modes, selected with -m / --mode:

# Binary (default)
bin/tpc.php app.php -o myapp

# PHP extension
bin/tpc.php extension/ -m ext -o my_extension

# Shared library; also generates mylib.stub.php
bin/tpc.php lib/ -m lib -o mylib

See Compilation modes for details.

For multi-file projects, keep repeatable build settings in project.yml:

name: myapp
mode: bin
php-version: "8.5"
optimize: 2
job: 8
build-dir: build
cxx-std: c++17

sources:
  - src
  - cpp-src
  - path: src/php85
    if: PHP_VERSION_ID >= 80500
  - path: src/windows
    if: PHP_OS_FAMILY == "Windows"

ignore:
  - src/experimental

include-paths:
  - native/include
defines:
  - FEATURE_FAST_PATH=1
link-paths:
  - native/lib
link-libs:
  - curl

# Zend extension requirements, not native linker libraries.
# `extension-dependencies` is the equivalent long name; do not use both.
ext-deps:
  - pdo_mysql
  - curl

Paths are resolved relative to the YAML file. A source entry may be a file or directory; conditional entries support PHP_VERSION, PHP_VERSION_ID, and PHP_OS_FAMILY. CLI arguments override their YAML counterparts. Native linker dependencies belong in link-libs; ext-deps writes ZEND_MOD_REQUIRED entries so Zend can reject loading when a required PHP extension is missing.

The build directory contains generated C++, dependency objects, and the precompiled-header cache. Reusing it makes incremental builds much faster; use --force only when the reusable PHPX objects must be rebuilt.

See Compiler CLI for all project keys and command-line precedence rules.

TypePHP follows PHP syntax and runtime behavior where they are compatible with ahead-of-time compilation, but it also makes several deliberate restrictions:

• global scope is declaration-only; executable statements must be inside a function or method;
• binary mode has a strict main() signature;
• use native_types opts scalar declarations into fixed native storage, so a value cannot later change to an incompatible type;
• statically-known calls and properties are compiled directly, while supported dynamic operations use PHPX/Zend runtime fallbacks;
• .stub.php files declare C++ or imported-library APIs and must contain empty bodies; #[Native] classes are not permitted in stub files;
• some highly dynamic reference, declaration, closure, and reflection patterns remain intentionally unsupported.

The compatibility boundary is part of the public contract and has both positive and negative tests. Consult Incompatible PHP features for the current, specific list instead of assuming that absence from this README means support.

TypePHP consumes its built-in code-generation attributes while lowering the class. The generated methods retain the declared property types and take part in the same conflict, inheritance, and final-method checks as explicitly declared methods.

<?php

#[Printer(fields: ['id', 'name'])]
#[Arrayable(fields: ['id', 'name'])]
final class User
{
    #[Constructor, Getter, With]
    public int $id;

    #[Constructor, Getter, Setter]
    public string $name = 'guest';
}

function main(): void
{
    $user = new User(7);
    $user->setName('Alice');

    $copy = $user->withId(8);
    echo $user->getId();       // 7
    echo $copy->getId();       // 8
    echo $user;                // User(id=7, name=Alice)
    echo $user->toArray()['name'];
}

Without fields, #[Printer] and #[Arrayable] use the class's own public instance properties. The positional form, such as #[Arrayable(['id'])], is equivalent to #[Arrayable(fields: ['id'])].

#[Getter], #[Setter], and #[With] cannot target static properties or properties with hooks. #[Setter] and #[With] additionally reject readonly properties. #[Constructor] cannot be used when the class already declares __construct(), and required constructor properties must precede properties with defaults. A generated method name that conflicts with a declared or inherited final method is a compile-time error.

<?php
use native_types;

function fib(int $n): int
{
    if ($n == 1 || $n == 2) {
        return 1;
    }
    return fib($n - 1) + fib($n - 2);
}

function main(int $argc, array $argv): void
{
    $n = (int)$argv[1];
    $begin = microtime(true);
    echo fib($n) . "\n";
    echo "Time: " . (microtime(true) - $begin) . "\n";
}

bin/tpc.php fib.php -O3 -o fib
./fib 30

With use native_types, int variables become C++ int64_t and arithmetic compiles to plain CPU instructions instead of ZendVM calls.

<?php
declare(strict_types=1);
use native_types;

function main(): void
{
    // 54-digit integer — automatically detected and stored as bigInt
    $a = std::bigInt("123456789012345678901234567890123456789012345678901234");
    $b = std::bigInt("987654321098765432109876543210987654321098765432109876");

    echo $a->add($b)->toString() . "\n";   // exact, no overflow

    // Exact decimal arithmetic — no binary floating-point error
    $c = std::decimal("0.1")->add(std::decimal("0.2"));
    echo $c->toString() . "\n";            // "0.3"

    // 256-bit floating point
    $pi = std::bigFloat("3.14159265358979323846264338327950288419716939937510");
    echo $pi->mul(2)->toString() . "\n";
}

See High-precision types and Native types.

<?php
use native_types;

function main(): void
{
    $vector = std::vector(Type::Int);

    $vector[] = 1;
    $vector[] = 2;
    $vector[] = 3;

    $sum = 0;
    foreach ($vector as $value) {
        $sum += $value;
    }

    echo $sum . "\n";       // 6
    echo $vector[1] . "\n"; // 2

    // key-value map with fixed key/value types
    $map = std::ordered_map(Type::String, Type::Int);
    $map["a"] = 1;
    $map["b"] = 2;
}

See Std containers.

<?php

function main(): void
{
    $s = "hello world";
    echo $s->length() . "\n";       // strlen()
    echo $s->upper() . "\n";        // strtoupper()
    echo $s->substr(0, 5) . "\n";   // substr()

    $arr = [1, 3, 5, 7, 9];
    echo $arr->count() . "\n";      // count()
    var_dump($arr->contains(3));    // in_array()

    $big = std::bigInt("12345678901234567890");
    echo $big->mul(2)->toString() . "\n";
}

Method calls on primitives are resolved at compile time into direct C/C++ function calls — no vtable lookup, no reflection, no runtime dispatch. See Universal methods.

Write performance-critical kernels in C++ and call them from PHP:

// math.cpp
#include <phpx.h>

using namespace php;

Int php_fast_sum(Int a, Int b) {
    return a + b;
}

<?php
// math.stub.php — declares the C++ function signature
function fast_sum(int $a, int $b): int {}

<?php
function main(): void
{
    echo fast_sum(3, 4) . "\n";  // 7
}

Add math.cpp, math.stub.php, and the calling PHP source to the same project configuration. The php_ C++ symbol prefix is the TypePHP callable ABI; stub functions provide type metadata only and must not contain an implementation.

See Mixed C++/PHP.

TypePHP runs the official bench.php and micro_bench.php language benchmarks that ship with the PHP source tree, compiled with -O3:

Both benchmarks measure core PHP language performance — function calls, object property access, array/hash access, string handling, control flow, and more. The checked-in workloads are benchmark/bench.php and benchmark/micro_bench.php. Additional focused performance regressions live in the same benchmark/ directory.

These numbers are a project measurement snapshot, not a performance guarantee. PHP version, compiler, CPU, optimization flags, and enabled extensions can all change the result; compare on the same machine with the same workload before making deployment decisions.

A 10000×100000 element update loop, comparing PHP arrays against TypePHP's std::array and native C++:

std::array is roughly 10× faster than PHP arrays and performs close to the hand-written C++ result in this workload. See the benchmark in Std containers.

bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]

Common usage:

# Compile a single file
bin/tpc.php app.php

# Optimize and run, passing args to the program after `--`
bin/tpc.php app.php -O3 -r -- --flag value

# Compile a project defined in project.yml
bin/tpc.php project.yml -O2 -j 8

# Build a PHP extension
bin/tpc.php extension/ -m ext -o my_extension

# Only generate C++ (skip compile & link)
bin/tpc.php app.php --dry --build-dir /tmp/typephp-build

# Compile to WASI 0.2
bin/tpc.php --wasm app.php

# Compile for the browser (requires jco)
bin/tpc.php --wasm=browser app.php

Key options:

Run bin/tpc.php --help for the authoritative, up-to-date list. See Compiler CLI for details, including Bash completion:

source <(./tpc --generate-completion=bash)

• libphp.so / libphp.dylib is missing: install/build the matching PHP embed SAPI, set PHP_HOME, or let bin/tpc.php offer the interactive Linux installer.
• PHPX cannot be found: set PHPX_HOME to a PHPX installation containing include/ and lib/libphpx.so (or the platform equivalent), then build PHPX before compiling the project.
• Startup crashes or ABI errors: the PHP headers, php-config, libphp, and loaded extension ABI must agree on the PHP version and ZTS/NTS mode. Do not mix artifacts from different PHP builds.
• Incremental builds are unexpectedly slow: keep a stable --build-dir so object and PCH caches can be reused. When an external test runner already runs several tests concurrently, avoid multiplying that concurrency by an unnecessarily large tpc -j value.
• A project compiles with bin/tpc.php but fails with tpc: reproduce with the self-hosted compiler. Bootstrap execution can expose dynamic-call or ABI paths that the PHP-hosted compiler does not exercise.

TypePHP ships a Python tool submodule that shares the tpc entry point:

# Generate IDE helpers for Python modules
./tpc --gen-python-helper math
./tpc --gen-python-helper numpy --output-dir .ide-helper

# Convert a Python script to TypePHP
./tpc --convert-python-to-php script.py > script.php

See Python tool submodule.

Install development dependencies and run the compiler unit suite:

composer install
PHPX_HOME=/path/to/phpx vendor/bin/phpunit

PHPT is the end-to-end suite. Build the self-hosted compiler first and pass it explicitly to the test runner; using the Zend PHP executable as --compiler does not test the deployed compiler:

PHPX_HOME=/path/to/phpx php bin/tpc.php project.yml --job 2 --no-progress
php run-tests.php -q -j8 --compiler ./tpc tests/compiler

Static analysis and the source-derived coverage matrix are separate checks:

composer analyse
php bin/analyze-test-coverage.php
php bin/analyze-test-coverage.php \
  --format=markdown --output=build/test-coverage.md --strict

The coverage tool reports PHP version × feature × positive compilation × runtime semantics × negative diagnostics, plus concrete PHP-parser AST nodes. It intentionally does not publish a single percentage without an explicit denominator. See Test coverage analyzer.

GitHub Actions runs PHPUnit and self-hosted PHPT on PHP 8.4 and 8.5. Changes to compiler behavior should add a focused PHPUnit test for internal/code-generation rules and a PHPT whenever runtime output or diagnostics are observable.

• Quick Start — minimal compilation flow
• Compilation modes — bin, ext, lib
• Compiler CLI — CLI arguments and project config
• Incompatible PHP features — current limits
• Native types — native scalar types
• High-precision types — BigInt / Decimal / BigFloat
• Std containers — strongly-typed containers
• Universal methods — compile-time method resolution
• Compile-time functions — any(), refval(), objval(), …
• Mixed C++/PHP — C++/PHP interop
• #[Immutable] — compile-time read-only contracts
• #[ArrayDef] — typed array-property contracts
• Property hooks — PHP 8.4 hook lowering and runtime metadata
• Object storage models — Zend object, Box, and Native class boundaries
• Generators — generator lowering and lifecycle
• Test coverage analyzer — AST and feature evidence matrix
• WASI build — WASI targets

TypePHP is licensed under the GNU General Public License v3.0.

• Repository: https://github.com/swoole/typephp
• Copyright © 2026 上海识沃网络科技有限公司 (Swoole)