TinyPHP
Documentation

文档

从快速开始到编译流水线，全面了解 TinyPHP 的语法与能力。

快速开始

TinyPHP 是一个 PHP → C AOT 编译器，用 PHP 8.5 强类型语法编写原生二进制，零运行时依赖，性能提升 300-500 倍。下载源码后即可通过 tphp.php 入口编译 PHP 文件为可执行二进制。

编译单文件

php tphp.php test/var/var.php

编译多文件

多文件按入口顺序合并编译，被依赖文件需显式列出：

php tphp.php main.php demo.php

编译 C 互操作

桥接 PHP 与 C 源码时，将 .c 文件直接追加到命令末尾：

php tphp.php main.php bridge.php lib.c

CLI 选项

常用命令行选项：

  • -o <output> 输出文件路径
  • -cc <compiler> 指定 C 编译器（默认内置 TCC）
  • -os <target> 跨编译目标：windows / linux / macos
  • -arch <arch> 目标架构：x86_64 / aarch64
  • -shared 编译为动态库
  • --debug 编译运行并比对 #debug 预期输出

第一个程序 Hello World

每个程序需要一个 Main 类与 main() 入口方法：

<?php
class Main {
    public function main(): void {
        echo "hello world\n";
    }
}

#debug 测试驱动

使用 #debug 注释声明预期输出，配合 --debug 自动比对：

<?php
#debug int(42)
#debug string(5) "hello"

class Main {
    public function main(): void {
        var_dump(42);
        var_dump("hello");
    }
}

运行比对：

php tphp.php test.php --debug

语法特性

基于 PHP 8.5 强类型语法，约 80% PHP 兼容性。下列特性均已在 AOT 编译器中实现。

控制流

if/elseif/else while do-while for foreach switch match break/continue goto

OOP 面向对象

class extends abstract interface implements trait + use enum __construct(public $x) __destruct static / final / readonly instanceof self:: $this ?-> 空安全

闭包

function() use($x) {} fn($x): T => expr 多捕获 嵌套闭包

异常

try/catch/finally throw error() 抛出 Type|Exception 返回类型 never

类型系统

int float string bool array array<T> 泛型数组 callable void mixed self 类类型

运算符

完整 15 级优先级 三元 ?: 空合并 ?? 太空船 <=>

命名空间

namespace A\B use A\{B,C} 分组导入 use function / const

Generator 生成器

yield yield $k => $v send() getReturn()
不支持：eval()、$$var、include/require、__call/__get/__set。 这些特性在 AOT 物理不可行，详见 README 中的替代方案。

C 互操作 PHPC

PHPC 是 TinyPHP 与 C 语言互操作的核心能力。通过编译期指令与类型注解，可直接调用 C 函数、操作 C 指针与结构体。

#include 与 #flag 指令

支持按平台条件包含头文件与链接标志：

#include "include/demo.h"
#include Linux "linux_only.h"
#include Windows <windows.h>
#flag Linux -lm
#flag GCC -O2 -DNDEBUG

C 类型注解

使用 C.T* 表示 C 指针类型，C.<type> 表示 C 标量类型：

function create_origin(): C.Point* {
    return C->point_origin();
}
function get_point_x(C.Point* $p): C.double {
    return C->point_get_x($p);
}

直接调用 C

使用 C->function(args) 调用 C 函数，使用 C->CONST 读取 C 常量。

数组互操作

PHP 数组转换为 C 数组的桥接函数：

  • phpc_arr_int($arr) — int 数组
  • phpc_arr_dbl($arr) — double 数组
  • phpc_arr_str($arr) — string 数组

对象与回调互操作

  • phpc_obj($obj) / phpc_new_obj — 对象互操作
  • phpc_fn_i32($cb) / phpc_env($cb) — 回调互操作
所有权规则： phpc_arr_int/dbl 自动注册；phpc_arr_str 需 defer phpc_free_str_arr； c_str/phpc_obj 借用不可 free；C 库返回的 T* 用 defer C->free 释放。

内置函数

312+ 内置函数，覆盖 PHP 标准库核心子集，全部以 AOT 编译进原生二进制。

函数分类

数组 array_* / count / sort / push / merge / splice 字符串 strlen / substr / str_replace / sprintf / explode / implode 数学 abs / ceil / floor / round / max / min / pow / sqrt / log / exp / trig 时间 time / date / mktime / strtotime JSON json_encode / json_decode 哈希 md5 / sha1 / sha256 / hash / hmac / password_hash / password_verify PCRE 正则 preg_match / preg_replace / preg_split（NFA VM） iconv 字符集转换 filter_var 过滤器 多线程 Thread / Mutex / CondVar / WaitGroup zlib gzip 压缩 + 流式 + 增量上下文 zip 归档读写 stream socket stream CSPRNG random_bytes / random_int ctype

查看完整函数列表

多线程

TinyPHP 内置原生多线程支持，提供 Thread / Mutex / CondVar / WaitGroup 四类原语，可直接编译为 OS 线程。

<?php
class Main {
    public function main(): void {
        $t = new Thread(function(): int {
            return 42;
        });
        $t->start();
        echo $t->join();  // 42

        $wg = new WaitGroup();
        $wg->add(1);
        $t2 = new Thread(function() use ($wg): int {
            $wg->done();
            return 0;
        });
        $t2->start();
        $wg->wait();
        $t2->join();

        $mutex = new Mutex(false);
        $mutex->lock();
        // 临界区
        $mutex->unlock();
    }
}

线程原语

  • Thread — start / join / detach + 静态 yield / sleep / id
  • Mutex — lock / tryLock / unlock，支持 recursive 选项
  • CondVar — wait / signal / broadcast
  • WaitGroup — add / done / wait
Thread-Local 运行时策略：每线程独立内存池，无锁竞争，避免 GC STW 全局停顿。

扩展系统

通过 #import 指令导入内置扩展，扩展函数直接编译进二进制。

#import 语法

<?php
#import pcntl

class Main {
    public function main(): void {
        $pid = pcntl_fork();
    }
}

内置扩展

pcntl posix openssl calendar exif pcre pdo pdo_mysql sqlite3 stream fileinfo filter hash iconv
安全模型：#import 受扩展名白名单（正则 \w[\w\-]*）+ 工作区边界校验（realpath 后必须在 ext/ 目录内）双重约束，杜绝路径穿越。

编译流水线

从 PHP 源码到原生二进制的完整 AOT 流水线：

PHP → Lexer → Token[] → Parser → AST → CodeGenerator → .c → 编译器 → 二进制

阶段说明

  • Lexer — 逐字符扫描，约 75 种 Token，支持字符串插值 / heredoc
  • Parser — 递归下降，运算符优先级完整
  • CodeGenerator — 访问者模式，生成类型安全的 C 代码
  • C 运行时 — COS 风格对象系统（16B 头），setjmp/longjmp 异常，ROPE 字符串拼接，128 槽数组/对象复用池，64KB 字符串池
  • 编译器 — 内置 TCC（mob 分支），支持 GCC / Clang