aot
/
compiler
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(readme): rewrite documentation with comprehensive TypePHP guide

Browse Source 
- Completely redesigned README structure with English and Chinese versions
- Added detailed explanation of TypePHP as an AOT compiler for PHP
- Documented core features including native type system, high-precision numerics, and typed containers
- Included comparison table showing benefits over traditional PHP execution models
- Provided comprehensive installation instructions and requirements
- Added quick start examples with code samples for different use cases
- Documented all three compilation modes (binary, extension, library)
- Included benchmark results demonstrating performance improvements
- Added detailed command line options and parameter
master
韩天峰 10 hours ago
parent 2986f3db70
commit 2c74be470e
2 changed files with 835 additions and 50 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 430
      README-CN.md
  2. 455
      README.md

430
README-CN.md
Unescape View File

@ -0,0 +1,430 @@
[简体中文](README-CN.md) | [English](README.md)
<div align="center">
# TypePHP
**PHP 原生 AOT 编译器**
将 PHP 源码提前（AOT）编译为原生机器码，生成独立的可执行文件、PHP 扩展和静态库，
同时保留你熟悉的 PHP 语法。
</div>
---
## 什么是 TypePHP？
TypePHP 是一个 AOT（Ahead-Of-Time，提前编译）编译器，它把 PHP 源码翻译为 C++，
再编译为原生机器码。与字节码缓存或虚拟机不同，它不会在运行时解释 opcode，
而是直接生成在 CPU 上运行的原生二进制。
它保留熟悉的 PHP 语法，同时引入编译期类型信息，让编译器为你的性能热点生成快速、
静态类型的 C++ 代码，而其余代码仍运行在久经考验的 Zend 引擎上。
## 特性
- **真正的 AOT 编译** —— PHP 先降级为 C++17，再编译为原生机器码。无解释器、
无 opcode 缓存、无 JIT 预热。
- **三种构建模式** —— 同一份代码可编译为独立 `bin` 可执行文件、可加载的 PHP
`ext` 扩展，或 `lib` 静态库。
- **原生类型系统** —— `int`、`float`、`bool` 直接映射为 C++ 标量类型
（`int64_t`、`double`、`bool`），数值代码可获得数量级的性能提升。
- **高精度数值** —— `bigInt`（GMP）、`decimal`（libmpdec）、`bigFloat`（MPFR），
零开销算术运算。
- **强类型容器** —— `std::array`、`std::vector`、`std::map`、`std::ordered_map`，
元素类型在编译期确定；最高比 PHP 数组快 **10 倍**，性能与 C++ `std::vector` 相当。
- **通用方法（Universal Methods）** —— 在原生类型上直接调用方法
（`$s->upper()`、`$arr->contains()`、`$big->mul(2)`），零运行时派发开销。
- **混合 C++ / PHP 编程** —— 在性能关键内核中直接调用 C++ 函数（反之亦然）。
- **编译期函数与关键词** —— `any()`、`refval()`、`objval()`、`expected()`、
`unexpected()`，以及 `toInt()`、`toString()`、`toArray()` 等。
- **编译期安全检查** —— `#[Immutable]` 只读契约和 `#[ArrayDef]` 数组结构元数据，
在编译期检查，零运行时开销。
- **现代 PHP 支持** —— PHP 8.4 property hooks、非对称可见性、PHP 8.5
`clone()`-with 以及 `(void)` 丢弃表达式。
- **跨平台与 WASM** —— 面向 x86-64 和 ARM64 的 Linux、Windows、macOS 目标，
以及 WASI 0.2 和浏览器（Jco）输出。
- **Python 桥接** —— 为 Python 模块生成 IDE helper，并将 Python 脚本转换为 TypePHP。
## 为什么选择 TypePHP？
| | TypePHP AOT | 字节码缓存（OPcache） | JIT（PHP 8+） |
|---|---|---|---|
| 编译目标 | 原生机器码 | 字节码 | 机器码（trace） |
| 启动 / 预热 | 无（已编译完成） | 每进程预热 | JIT 预热 |
| 类型驱动优化 | 编译期、全程序 | 无 | 有限，基于 trace |
| 独立可执行文件 | 支持 | 不支持 | 不支持 |
| 源码保护 | 编译为机器码 | 字节码（可还原） | 字节码（可还原） |
| 性能确定性 | 是 | 否 | 否 |
**相较原生 PHP 的优势：**
- **接近原生的性能。** 数值密集和容器密集的热点路径会编译为与 C++ 程序相同的机器码。
见下方[基准测试](#基准测试)。
- **源码保护。** 源码被编译掉——交付物是原生二进制，而不是可读的 PHP 文件。
- **零依赖部署。** 二进制模式生成单个自包含可执行文件，无需 PHP 运行时即可运行。
- **渐进式类型，真正带来收益。** 只在性能关键处添加 `use native_types`、`std::`
容器和类型声明，其余保持普通 PHP。
- **完整 PHP 生态互通。** 扩展模式以标准 PHP 扩展形式加载到 `php-fpm`，
现有框架和工具链可继续使用。
## 前置要求
- **PHP 8.4 – 8.5**，需包含 `embed` 模块（`libphp.so`）
- **GCC 9+**（或 Clang），支持 **C++17**
- **CMake 3.24+**
- 高精度数学库：**GMP**、**MPFR**、**libmpdec**
```shell
# Ubuntu/Debian
sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
# RHEL/CentOS/Fedora
sudo dnf install gmp-devel mpfr-devel libmpdec-devel
# Arch Linux
sudo pacman -S gmp mpfr mpdecimal
```
> GMP 用于 `bigInt`，MPFR 用于 `bigFloat`，libmpdec 用于 `decimal`。
预览版目前以 **Linux** 为主要开发平台（推荐 Ubuntu 22.04）。Windows 和 macOS
打包通过同一入口点支持。
## 安装
### 通过 Composer
```bash
composer require --dev swoole/typephp
```
然后编译你的项目：
```bash
vendor/bin/tpc.php project.yml
```
在 TypePHP 源码仓库中开发时，改用本地入口：
```bash
bin/tpc.php project.yml
```
### 构建 `libphp.so`
`tpc` 需要以 `embed` SAPI 构建的 PHP。如果 Linux 上缺少 `libphp.so`，
`tpc.php` 可以交互式下载 PHP 源码并自动构建。详见
[自动构建 libphp.so](docs/LIBPHP_INSTALLER.md)。
## 快速开始
创建 `hello.php`：
```php
<?php
function main(): void
{
echo "Hello World!\n";
var_dump(PHP_VERSION);
var_dump(php_uname());
}
```
编译并运行：
```bash
bin/tpc.php hello.php
./hello
```
输出：
```
Hello World!
string(5) "8.4.x"
string(16) "Linux ..."
```
> 二进制模式需要全局 `main()` 函数。它可以声明为无参数，或
> `main(int $argc, array $argv)` 以接收命令行参数，且必须返回 `void`。
## 编译模式
TypePHP 支持三种构建模式，通过 `-m` / `--mode` 选择：
| 模式 | 参数 | 输出 | 需要 `main()` | 典型用途 |
|---|---|---|---|---|
| 二进制 | `-m bin`（默认） | 可执行文件 | 是 | CLI 工具、常驻服务、独立应用 |
| 扩展 | `-m ext` | `.so` / `.dll` | 否 | `php-fpm` 上的 Web 应用、即插即用 PHP 扩展 |
| 库 | `-m lib` | 静态库 | 否 | 将编译后的代码嵌入其他项目 |
```bash
# 二进制（默认）
bin/tpc.php app.php -o myapp
# PHP 扩展
bin/tpc.php extension/ -m ext -o my_extension
# 静态库
bin/tpc.php lib/ -m lib -o mylib
```
详见[编译模式](docs/COMPILATION_MODES.md)。
## 使用示例
### 1. 原生类型 —— 编译期数值加速
```php
<?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";
}
```
```bash
bin/tpc.php fib.php -O3 -o fib
./fib 30
```
使用 `use native_types` 后，`int` 变量变为 C++ `int64_t`，算术运算直接编译为
CPU 指令，而不是 ZendVM 调用。
### 2. 高精度数值
```php
<?php
declare(strict_types=1);
use native_types;
function main(): void
{
// 54 位整数 —— 自动识别并存储为 bigInt
$a = std::bigInt("123456789012345678901234567890123456789012345678901234");
$b = std::bigInt("987654321098765432109876543210987654321098765432109876");
echo $a->add($b)->toString() . "\n"; // 精确计算，不会溢出
// 精确的十进制运算 —— 无二进制浮点误差
$c = std::decimal("0.1")->add(std::decimal("0.2"));
echo $c->toString() . "\n"; // "0.3"
// 256 位浮点数
$pi = std::bigFloat("3.14159265358979323846264338327950288419716939937510");
echo $pi->mul(2)->toString() . "\n";
}
```
详见[高精度类型](docs/HIGH_PRECISION_TYPES.md)和[原生类型](docs/NATIVE_TYPES.md)。
### 3. 强类型容器
```php
<?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 = std::ordered_map(Type::String, Type::Int);
$map["a"] = 1;
$map["b"] = 2;
}
```
详见 [Std 容器](docs/STD_CONTAINERS.md)。
### 4. 通用方法
```php
<?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";
}
```
原生类型上的方法调用在编译期被解析为直接的 C/C++ 函数调用——没有虚表查找、
没有反射、没有运行时派发。详见[通用方法](docs/UNIVERSAL_METHODS.md)。
### 5. 混合 C++ / PHP
用 C++ 编写性能关键内核，并在 PHP 中调用：
```cpp
// math.cpp
#include <phpx.h>
using namespace php;
var php_fast_sum(Int a, Int b) {
return a + b;
}
```
```php
<?php
// math.stub.php —— 声明 C++ 函数签名
function fast_sum(int $a, int $b): int;
```
```php
<?php
function main(): void
{
echo fast_sum(3, 4) . "\n"; // 7
}
```
详见[混合 C++/PHP](docs/MIXED_CPP_PHP.md)。
## 基准测试
一个 10000×100000 的元素累加循环，对比 PHP 数组、TypePHP `std::array`
与原生 C++：
| 实现 | 耗时 |
|---|---|
| PHP 数组（JIT） | 67.6 秒 |
| `std::array`（TypePHP AOT） | **6.4 秒** |
| C++ `std::vector` | 6.2 秒 |
`std::array` 比 PHP 数组快约 **10 倍**，性能与手写 C++ 完全一致。
完整基准测试见 [Std 容器](docs/STD_CONTAINERS.md)。
## 命令行
```bash
bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]
```
常用示例：
```bash
# 编译单个文件
bin/tpc.php app.php
# 优化并运行，`--` 后的参数传给生成的程序
bin/tpc.php app.php -O3 -r -- --flag value
# 编译 project.yml 定义的项目
bin/tpc.php project.yml -O2 -j 8
# 生成 PHP 扩展
bin/tpc.php extension/ -m ext -o my_extension
# 只生成 C++（跳过编译与链接）
bin/tpc.php app.php --dry --build-dir /tmp/typephp-build
# 编译为 WASI 0.2
bin/tpc.php --wasm app.php
# 编译为浏览器目标（需要 jco）
bin/tpc.php --wasm=browser app.php
```
主要选项：
| 选项 | 说明 |
|---|---|
| `-O <0-3>` | 优化级别（默认 `0`） |
| `-d`, `--debug` | 调试构建，带符号和源码跟踪 |
| `-o`, `--output <file>` | 输出文件名 |
| `-m`, `--mode <bin\|lib\|ext>` | 构建模式（默认 `bin`） |
| `-r`, `--run` | 构建成功后运行 |
| `-j`, `--job <num>` | 并行编译任务数（默认 `4`） |
| `--build-dir <dir>` | 生成 C++ 与中间产物的目录 |
| `--dry` | 只生成 C++，跳过编译与链接 |
| `--php-version <8.4\|8.5>` | 接受的 PHP 语法版本 |
| `--cxx-std <ver>` | C++ 标准（如 `c++17`、`c++20`） |
| `--march <arch>` | 目标指令集（如 `native`） |
| `--lto` | 启用链接时优化 |
| `--sanitize <type>` | 启用 sanitizer（如 `address`） |
运行 `bin/tpc.php --help` 查看权威的最新参数列表。详见
[编译器命令行](docs/COMPILER_CLI.md)，包括 Bash 补全：
```bash
source <(./tpc --generate-completion=bash)
```
## Python 桥接
TypePHP 内置一个 Python 工具子模块，复用 `tpc` 入口：
```shell
# 为 Python 模块生成 IDE helper
./tpc --gen-python-helper math
./tpc --gen-python-helper numpy --output-dir .ide-helper
# 将 Python 脚本转换为 TypePHP
./tpc --convert-python-to-php script.py > script.php
```
详见 [Python 工具子模块](docs/python/tools.md)。
## 文档
- [快速入门](docs/QUICKSTART.md) —— 最小编译流程
- [编译模式](docs/COMPILATION_MODES.md) —— `bin`、`ext`、`lib`
- [编译器命令行](docs/COMPILER_CLI.md) —— CLI 参数与项目配置
- [不兼容 PHP 特性清单](docs/INCOMPATIBLE_PHP_FEATURES.md) —— 当前限制
- [原生类型](docs/NATIVE_TYPES.md) —— 原生标量类型
- [高精度类型](docs/HIGH_PRECISION_TYPES.md) —— BigInt / Decimal / BigFloat
- [Std 容器](docs/STD_CONTAINERS.md) —— 强类型容器
- [通用方法](docs/UNIVERSAL_METHODS.md) —— 零开销方法
- [编译期函数](docs/COMPILE_TIME_FUNCTIONS.md) —— `any()`、`refval()`、`objval()` 等
- [混合 C++/PHP](docs/MIXED_CPP_PHP.md) —— C++/PHP 互操作
- [`#[Immutable]`](docs/IMMUTABLE.md) —— 编译期只读契约
- [WASI 构建](docs/WASI_BUILD.md) —— WASI 目标
## 授权协议
TypePHP 采用 [GNU General Public License v3.0](LICENSE) 授权。
## 社区
- 代码仓库：<https://github.com/swoole/typephp>
- 版权所有 © 2026 上海识沃网络科技有限公司（Swoole）

455
README.md
Unescape View File

@ -1,94 +1,449 @@
# 依赖
- 编译器和生成程序均需要 PHP 8.4 以上版本，支持 PHP 8.4～8.5
- 需要 GCC-9 以上版本，支持 C++17 标准
- 需要 CMake-3.24 以上版本
- 需要高精度数学库：`GMP`、`MPFR`、`libmpdec`
[English](README.md) | [简体中文](README-CN.md)
# Composer 安装
<div align="center">
在项目中安装 TypePHP：
# TypePHP
**A native AOT compiler for PHP**
Compile PHP source code into native machine code ahead of time — producing
standalone executables, PHP extensions, and static libraries — while keeping
the PHP syntax you already know.
</div>
---
## What is TypePHP?
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 your hot paths — while the
rest of your code continues to run on the battle-tested Zend engine.
## Features
- **True AOT compilation** — PHP is lowered to C++17, then to native machine
code. No interpreter, no opcode cache, no JIT warm-up.
- **Three build modes** — build a standalone `bin` executable, a loadable PHP
`ext` extension, or a `lib` static 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 zero-overhead arithmetic.
- **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)`) with zero runtime
dispatch overhead.
- **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.
- **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 x86-64 and
ARM64, plus WASI 0.2 and browser (Jco) output.
- **Python bridge** — generate IDE helpers for Python modules and convert
Python scripts to TypePHP.
## Why TypePHP?
| | TypePHP AOT | Opcode cache (OPcache) | JIT (PHP 8+) |
|---|---|---|---|
| Compilation target | Native machine code | Bytecode | Machine code (trace) |
| Startup / warm-up | None (already compiled) | Per-process warm-up | JIT warm-up |
| Type-driven optimization | Compile-time, full-program | None | Limited, trace-based |
| Standalone executable | Yes | No | No |
| Source code protection | Compiled to machine code | Bytecode (reversible) | Bytecode (reversible) |
| Deterministic performance | Yes | No | No |
**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](#benchmark) below.
- **Source protection.** Your source is compiled away — shipped artifacts are
native binaries, not readable PHP files.
- **Zero-dependency deployment.** Binary mode produces a single self-contained
executable that runs without a PHP runtime.
- **Gradual typing that actually pays off.** Add `use native_types`, `std::`
containers, and type declarations only where performance matters; the rest
stays ordinary PHP.
- **Full PHP ecosystem interop.** Extension mode loads as a standard PHP
extension into `php-fpm`, so existing frameworks and tooling keep working.
## Requirements
- **PHP 8.4 – 8.5** with the `embed` module (`libphp.so`)
- **GCC 9+** (or Clang) with **C++17**
- **CMake 3.24+**
- High-precision math libraries: **GMP**, **MPFR**, **libmpdec**
```shell
# Ubuntu/Debian
sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
# RHEL/CentOS/Fedora
sudo dnf install gmp-devel mpfr-devel libmpdec-devel
# Arch Linux
sudo pacman -S gmp mpfr mpdecimal
```
> GMP powers `bigInt`, MPFR powers `bigFloat`, and libmpdec powers `decimal`.
The preview currently targets **Linux** as the primary development platform
(Ubuntu 22.04 recommended). Windows and macOS packaging is supported through
the same entry point.
## Installation
### Via Composer
```bash
composer require --dev swoole/typephp
```
安装后可直接编译项目：
Then compile your project:
```bash
vendor/bin/tpc.php project.yml
```
在 TypePHP 源码仓库中则使用：
When working inside the TypePHP source repository, use the local entry point
instead:
```bash
bin/tpc.php project.yml
```
Linux 环境缺少 `libphp.so` 时，`tpc.php` 可以交互式下载 PHP 源码并自动构建，详见 [自动构建 libphp.so](docs/LIBPHP_INSTALLER.md)。
### Building `libphp.so`
Python namespace IDE helper 与 Python 源码转换也使用同一入口：
`tpc` requires a PHP built with the `embed` SAPI. If `libphp.so` is missing on
Linux, `tpc.php` can interactively download the PHP source and build it for
you. See [Automatic libphp.so build](docs/LIBPHP_INSTALLER.md).
```shell
./tpc --gen-python-helper math
./tpc --gen-python-helper numpy --output-dir .ide-helper
./tpc --convert-python-to-php script.py > script.php
## Quick Start
Create `hello.php`:
```php
<?php
function main(): void
{
echo "Hello World!\n";
var_dump(PHP_VERSION);
var_dump(php_uname());
}
```
详细说明见 [Python 工具子模块](docs/python/tools.md)。
Compile and run it:
```shell
# Ubuntu/Debian
sudo apt install libgmp-dev libmpfr-dev libmpdec-dev
```bash
bin/tpc.php hello.php
./hello
```
# RHEL/CentOS/Fedora
sudo dnf install gmp-devel mpfr-devel libmpdec-devel
Output:
# Arch Linux
sudo pacman -S gmp mpfr mpdecimal
```
Hello World!
string(5) "8.4.x"
string(16) "Linux ..."
```
> GMP 用于 `BigInt` 任意精度整数，MPFR 用于 `BigFloat` 高精度浮点数，libmpdec 用于 `Decimal` 十进制高精度小数。
> 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`.
> 预览版目前仅支持 `Linux` 系统，建议使用 `Ubuntu 22.04`
## Compilation Modes
## PHP
必须包含 embed 模块
TypePHP supports three build modes, selected with `-m` / `--mode`:
## PHPX
可使用 `composer install` 安装依赖。
进入 `vendor/swoole/phpx` 目录，编译 `phpx`
| Mode | Flag | Output | Needs `main()` | Typical use |
|---|---|---|---|---|
| Binary | `-m bin` (default) | Executable | Yes | CLI tools, long-running services, standalone apps |
| Extension | `-m ext` | `.so` / `.dll` | No | Web apps on `php-fpm`, drop-in PHP extension |
| Library | `-m lib` | Static library | No | Embedding compiled code into other projects |
```shell
cd vendor/swoole/phpx
cmake .
make -j32
```bash
# Binary (default)
bin/tpc.php app.php -o myapp
# PHP extension
bin/tpc.php extension/ -m ext -o my_extension
# Static library
bin/tpc.php lib/ -m lib -o mylib
```
## 动态链接库
```shell
sudo ldconfig -p | grep php
See [Compilation modes](docs/COMPILATION_MODES.md) for details.
## Examples
### 1. Native types — compile-time numeric speedup
```php
<?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";
}
```
必须包含 `libphp.so` 和 `libphpx.so`
若编译完成，但找不到动态链接库，需要修改
```shell
vim /etc/ld.so.conf.d/swoole.conf
```bash
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.
### 2. High-precision numerics
```php
<?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](docs/HIGH_PRECISION_TYPES.md) and
[Native types](docs/NATIVE_TYPES.md).
### 3. Strongly-typed containers
```php
<?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](docs/STD_CONTAINERS.md).
### 4. Universal methods
```php
<?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](docs/UNIVERSAL_METHODS.md).
### 5. Mixed C++ / PHP
Write performance-critical kernels in C++ and call them from PHP:
```cpp
// math.cpp
#include <phpx.h>
using namespace php;
var php_fast_sum(Int a, Int b) {
return a + b;
}
```
添加路径
```php
<?php
// math.stub.php — declares the C++ function signature
function fast_sum(int $a, int $b): int;
```
/home/swoole/workspace/projects/phpx/lib
/opt/php-8.4/lib/
```php
<?php
function main(): void
{
echo fast_sum(3, 4) . "\n"; // 7
}
```
## Release packaging
See [Mixed C++/PHP](docs/MIXED_CPP_PHP.md).
## Benchmark
A 10000×100000 element update loop, comparing PHP arrays against TypePHP's
`std::array` and native C++:
| Implementation | Time |
|---|---|
| PHP array (JIT) | 67.6 s |
| `std::array` (TypePHP AOT) | **6.4 s** |
| C++ `std::vector` | 6.2 s |
`std::array` is roughly **10× faster** than PHP arrays and performs
identically to hand-written C++. See the full benchmark in
[Std containers](docs/STD_CONTAINERS.md).
Use the same PHP entry point on Windows, Linux, and macOS:
## Command Line
```bash
bin/tpc.php <file|dir|project.yml> [options] [-- program-args...]
```
Common usage:
```bash
# 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:
| Option | Description |
|---|---|
| `-O <0-3>` | Optimization level (default `0`) |
| `-d`, `--debug` | Debug build with symbols and source tracking |
| `-o`, `--output <file>` | Output file name |
| `-m`, `--mode <bin\|lib\|ext>` | Build mode (default `bin`) |
| `-r`, `--run` | Run after a successful build |
| `-j`, `--job <num>` | Parallel compile jobs (default `4`) |
| `--build-dir <dir>` | Directory for generated C++ and intermediates |
| `--dry` | Generate C++ only, skip compile and link |
| `--php-version <8.4\|8.5>` | PHP syntax version to accept |
| `--cxx-std <ver>` | C++ standard (e.g. `c++17`, `c++20`) |
| `--march <arch>` | Target instruction set (e.g. `native`) |
| `--lto` | Enable link-time optimization |
| `--sanitize <type>` | Enable a sanitizer (e.g. `address`) |
Run `bin/tpc.php --help` for the authoritative, up-to-date list. See
[Compiler CLI](docs/COMPILER_CLI.md) for details, including Bash completion:
```bash
source <(./tpc --generate-completion=bash)
```
## Python bridge
TypePHP ships a Python tool submodule that shares the `tpc` entry point:
```shell
php package.php
# 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
```
Windows packaging requires `PHP_HOME` and `PHPX_HOME`; Linux packaging requires
UPX; macOS uses `strip` when available. TypePHP rejects 32-bit targets and
supports common 64-bit CPU architectures, including x86-64 and ARM64.
See [Python tool submodule](docs/python/tools.md).
## Documentation
- [Quick Start](docs/QUICKSTART.md) — minimal compilation flow
- [Compilation modes](docs/COMPILATION_MODES.md) — `bin`, `ext`, `lib`
- [Compiler CLI](docs/COMPILER_CLI.md) — CLI arguments and project config
- [Incompatible PHP features](docs/INCOMPATIBLE_PHP_FEATURES.md) — current limits
- [Native types](docs/NATIVE_TYPES.md) — native scalar types
- [High-precision types](docs/HIGH_PRECISION_TYPES.md) — BigInt / Decimal / BigFloat
- [Std containers](docs/STD_CONTAINERS.md) — strongly-typed containers
- [Universal methods](docs/UNIVERSAL_METHODS.md) — zero-overhead methods
- [Compile-time functions](docs/COMPILE_TIME_FUNCTIONS.md) — `any()`, `refval()`, `objval()`, …
- [Mixed C++/PHP](docs/MIXED_CPP_PHP.md) — C++/PHP interop
- [`#[Immutable]`](docs/IMMUTABLE.md) — compile-time read-only contracts
- [WASI build](docs/WASI_BUILD.md) — WASI targets
## License
TypePHP is licensed under the [GNU General Public License v3.0](LICENSE).
## Community
- Repository: <https://github.com/swoole/typephp>
- Copyright © 2026 上海识沃网络科技有限公司 (Swoole)

Write Preview
Loading…
Cancel
Save