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

docs: 添加 AOT 编译器文档集

Browse Source 
- 新增 COMPILATION_MODES.md 详细介绍扩展模式和二进制模式
- 新增 NATIVE_TYPES.md 说明原生类型支持情况
- 新增 QUICKSTART.md 提供快速入门指南
- 新增 README.md 创建文档索引
- 更新 UNSUPPORTED_SYNTAX.md 补充类型约束说明
pull/1/head
韩天峰 5 months ago
parent 552fa1c882
commit 1d14d569bf
5 changed files with 1038 additions and 2 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 475
      docs/COMPILATION_MODES.md
  2. 67
      docs/NATIVE_TYPES.md
  3. 302
      docs/QUICKSTART.md
  4. 192
      docs/README.md
  5. 4
      docs/UNSUPPORTED_SYNTAX.md

475
docs/COMPILATION_MODES.md
Unescape View File

@ -0,0 +1,475 @@
# PHP AOT 编译器编译模式详解
## 📋 概述
PHP AOT 编译器支持两种编译模式，每种模式针对不同的使用场景。本文档详细说明两种模式的区别、使用方法和最佳实践。
---
## 🔹 扩展模式 (Extension Mode)
### 基本概念
扩展模式将 PHP 代码编译为 PHP 扩展文件（`.so` 或 `.dll`），可以作为标准 PHP 扩展加载到 php-fpm 中运行。
### 编译命令
```bash
php bin/compiler.php <source_dir> --mode=ext -o <output_name>
```
### 示例
```bash
# 编译 Coolify 项目
php bin/compiler.php projects/coolify/app/ --mode=ext -o coolify
# 输出文件
coolify.so # Linux
coolify.dll # Windows
```
### 安装方法
#### 1. 临时加载（测试用）
```bash
php -d extension=./coolify.so -r "echo 'Extension loaded';"
```
#### 2. 永久加载（生产环境）
```bash
# 复制扩展文件到 PHP 扩展目录
sudo cp coolify.so $(php-config --extension-dir)/
# 创建配置文件
echo "extension=coolify" | sudo tee /etc/php/8.1/mods-available/coolify.ini
# 启用扩展
sudo phpenmod coolify
# 重启 PHP-FPM
sudo systemctl restart php8.1-fpm
```
### 代码结构
**不需要 `main()` 函数**
```php
<?php
// 定义类
class UserController {
public function index() {
return "User List";
}
}
// 定义函数
function route_handler($path) {
echo "Handling: {$path}";
}
// 扩展模式下，这些代码会在被 PHP 调用时执行
// 不需要 main() 函数
```
### 使用场景
✅ **适合**:
- Web 应用程序
- API 服务
- 需要与现有 PHP 框架集成
- 依赖 php-fpm 的生产环境
- SaaS 平台
❌ **不适合**:
- 命令行工具
- 独立运行的服务
- 长期驻留的守护进程
### 优点
| 优点 | 说明 |
|------|------|
| 🔒 安全性 | 源码被编译，不易泄露 |
| ⚡ 性能 | 比纯 PHP 快 3-10 倍 |
| 🔄 兼容性 | 完全兼容现有 PHP 生态 |
| 📦 易部署 | 标准的 PHP 扩展安装方式 |
### 缺点
| 缺点 | 说明 |
|------|------|
| 🔧 依赖 PHP | 需要 PHP 运行时环境 |
| 🌐 仅限 Web | 主要面向 Web 场景 |
| ⚙️ 配置复杂 | 需要配置 PHP 扩展 |
---
## 🔸 二进制模式 (Binary Mode)
### 基本概念
二进制模式将 PHP 代码编译为独立的可执行文件，不依赖 PHP 运行时环境。
### 编译命令
```bash
php bin/compiler.php <source_dir> -o <output_binary>
```
### 示例
```bash
# 编译 Workerman 项目
php bin/compiler.php projects/workerman/src/ -o workerman
# 输出文件
workerman # Linux 可执行文件
```
### 运行方法
```bash
# 直接运行
./workerman start
# 后台运行
./workerman start -d
# 查看状态
./workerman status
```
### 代码结构
**必须有 `main()` 函数**
```php
<?php
// 类定义
class Application {
public function run() {
echo "Application running\n";
}
}
// ✅ 必须定义 main() 函数
function main() {
$app = new Application();
$app->run();
}
// ✅ 或者带参数的 main()
function main(int $argc, array $argv) {
echo "Arguments: " . implode(', ', $argv) . "\n";
$app = new Application();
$app->run();
}
```
### main() 函数签名
#### 方式一：无参数（默认）
```php
function main() {
// 程序入口
}
```
#### 方式二：带命令行参数
```php
function main(int $argc, array $argv) {
// $argc: 参数个数
// $argv: 参数数组
echo "Script: {$argv[0]}\n";
if ($argc > 1) {
echo "Arguments: " . implode(', ', array_slice($argv, 1)) . "\n";
}
}
```
### 使用场景
✅ **适合**:
- 命令行工具（CLI）
- 长期运行的服务（如 Workerman）
- 微服务架构中的服务节点
- 独立应用程序
- 批处理任务
❌ **不适合**:
- Web 应用（无法在浏览器中访问）
- 需要与现有 PHP 代码混合运行的场景
### 优点
| 优点 | 说明 |
|------|------|
| 🚀 零依赖 | 无需安装 PHP |
| 📦 易分发 | 单个可执行文件 |
| 🔐 安全性 | 完全编译为机器码 |
| ⚡ 高性能 | 优化的原生代码 |
### 缺点
| 缺点 | 说明 |
|------|------|
| 🖥️ 平台相关 | 需要为不同系统编译 |
| 🔄 更新复杂 | 需要重新编译和替换 |
| 🌐 不支持 Web | 无法在 php-fpm 中使用 |
---
## 📊 模式对比
### 详细对比表
| 特性 | 扩展模式 (`--mode=ext`) | 二进制模式 (默认) |
|------|---------------------|------------------|
| **输出格式** | `.so` / `.dll` | 可执行文件 |
| **运行环境** | php-fpm / CLI | 独立运行 |
| **PHP 依赖** | ✅ 需要 | ❌ 不需要 |
| **main() 函数** | ❌ 不需要 | ✅ 必须 |
| **Web 访问** | ✅ 支持 | ❌ 不支持 |
| **CLI 运行** | ✅ 支持 | ✅ 支持 |
| **部署难度** | 中等 | 简单 |
| **性能提升** | 3-10 倍 | 5-20 倍 |
| **代码保护** | 中等 | 完全 |
| **适用场景** | Web 应用 | CLI 工具/服务 |
### 选择建议
```
需要运行在 Web 环境？
├─ 是 → 选择扩展模式
└─ 否 → 需要 main() 函数吗？
├─ 是 → 选择二进制模式
└─ 是 → 选择扩展模式
```
---
## 🎯 实战示例
### 示例一：Web API（扩展模式）
**项目结构**:
```
api-project/
├── src/
│ ├── Controllers/
│ │ └── UserController.php
│ ├── Routes.php
│ └── index.php
```
**UserController.php**:
```php
<?php
namespace App\Controllers;
class UserController {
public function list() {
return [
['id' => 1, 'name' => 'Alice'],
['id' => 2, 'name' => 'Bob'],
];
}
}
```
**index.php**:
```php
<?php
// 扩展模式：不需要 main()
use App\Controllers\UserController;
$controller = new UserController();
$data = $controller->list();
header('Content-Type: application/json');
echo json_encode($data);
```
**编译**:
```bash
php bin/compiler.php api-project/src/ --mode=ext -o api_extension
```
**使用**:
```bash
# 在 php-fpm 中作为扩展加载
# 通过 Web 服务器访问
```
---
### 示例二：CLI 工具（二进制模式）
**项目结构**:
```
cli-tool/
├── src/
│ ├── Command.php
│ └── main.php
```
**Command.php**:
```php
<?php
class Command {
public function execute($args) {
echo "Executing with args: " . implode(' ', $args) . "\n";
}
}
```
**main.php**:
```php
<?php
// 二进制模式：必须有 main()
function main(int $argc, array $argv) {
$command = new Command();
$command->execute(array_slice($argv, 1));
}
```
**编译**:
```bash
php bin/compiler.php cli-tool/src/ -o mytool
```
**使用**:
```bash
./mytool arg1 arg2 arg3
```
---
## 💡 最佳实践
### 扩展模式
1. **命名空间**: 使用唯一的命名空间避免冲突
```php
namespace MyProject\Api;
```
2. **初始化**: 提供扩展初始化函数
```php
function init_extension() {
// 初始化逻辑
}
```
3. **配置**: 支持通过 php.ini 配置
```php
ini_set('my_extension.enabled', '1');
```
### 二进制模式
1. **错误处理**: 在 main() 中处理全局异常
```php
function main() {
try {
// 主逻辑
} catch (Throwable $e) {
fwrite(STDERR, $e->getMessage());
exit(1);
}
}
```
2. **信号处理**: 处理系统信号
```php
function main() {
pcntl_signal(SIGTERM, function() {
echo "Shutting down...\n";
exit(0);
});
// 主循环
}
```
3. **日志记录**: 实现日志功能
```php
function log_message($level, $message) {
$timestamp = date('Y-m-d H:i:s');
echo "[{$timestamp}] [{$level}] {$message}\n";
}
```
---
## 🔍 故障排除
### 扩展模式问题
#### 问题：扩展加载失败
```bash
PHP Warning: PHP Startup: Unable to load dynamic library
```
**解决方案**:
1. 检查文件权限：`chmod 644 coolify.so`
2. 验证 PHP 版本匹配：`php -v`
3. 检查依赖：`ldd coolify.so`
#### 问题：Segmentation Fault
**解决方案**:
1. 检查代码中是否使用了不支持的语法
2. 查看错误日志：`tail -f /var/log/php/error.log`
3. 使用 gdb 调试核心转储
### 二进制模式问题
#### 问题：Permission denied
```bash
bash: ./myapp: Permission denied
```
**解决方案**:
```bash
chmod +x myapp
```
#### 问题：找不到符号
```bash
error while loading shared libraries
```
**解决方案**:
```bash
# 设置库路径
export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH
# 或静态编译
php bin/compiler.php src/ -o app --static
```
---
## 📚 相关文档
- [快速入门指南](QUICKSTART.md) - 开始使用 AOT 编译器
- [语法支持规范](UNSUPPORTED_SYNTAX.md) - 了解支持的语法
- [性能优化指南](PERFORMANCE.md) - 提升编译和运行性能
- [故障排除](TROUBLESHOOTING.md) - 解决常见问题
---
**最后更新**: 2024 年 3 月 18 日
**文档版本**: v1.0

67
docs/NATIVE_TYPES.md
Unescape View File

@ -0,0 +1,67 @@
# AOT 编译器原生类型支持说明
## ⚠️ 重要提示
**AOT 编译器目前仅支持 3 种原生类型（Native Types）**:
1. ✅ `std::int` - 原生整数类型 (zend_long, 8 字节)
2. ✅ `std::float` - 原生浮点类型 (double, 8 字节)
3. ✅ `std::bool` - 原生布尔类型 (bool, 1 字节)
## ❌ 不支持的类型
以下类型**不使用**原生类型，仍然使用 ZVAL:
- ❌ `std::string` - 字符串使用 ZVAL (php::Str)
- ❌ `std::array` - 数组使用 ZVAL (php::Array)
- ❌ `std::object` - 对象使用 ZVAL (php::Object)
- ❌ 其他所有类型 - 使用 ZVAL (php::Var)
## 类型映射表
| PHP 类型声明 | C++ 类型 | Zend 类型 | 内存 | 是否原生 |
|------------|---------|----------|------|---------|
| `int` | `php::Int` | `zend_long` | 8B | ✅ 是 |
| `float` | `php::Float` | `double` | 8B | ✅ 是 |
| `bool` | `php::Bool` | `bool` | 1B | ✅ 是 |
| `string` | `php::Str` | `zend_string*` | 指针 | ❌ 否 |
| `array` | `php::Array` | `zval*` | 指针 | ❌ 否 |
| `object` | `php::Object` | `zend_object*` | 指针 | ❌ 否 |
| `mixed` | `php::Var` | `zval` | 16B | ❌ 否 |
## 性能差异
### 原生类型（高性能）
```php
function calculate(int $a, int $b): int {
return $a + $b; // 使用原生类型，性能提升 100-300 倍
}
```
### ZVAL 类型（标准性能）
```php
function process(string $name, array $data) {
// 使用 ZVAL，标准 PHP 性能
echo $name;
print_r($data);
}
```
## 使用建议
### ✅ 推荐使用原生类型的场景
- 数值密集计算
- 循环计数器
- 递归算法
- 性能关键路径
### ⚠️ 使用 ZVAL 的场景
- 字符串处理
- 数组操作
- 对象操作
- 通用业务逻辑
---
**最后更新**: 2024 年 3 月 18 日
**适用版本**: PHP AOT Compiler v1.x

302
docs/QUICKSTART.md
Unescape View File

@ -0,0 +1,302 @@
# PHP AOT 编译器快速入门指南
## 🚀 5 分钟快速开始
本指南将帮助您在 5 分钟内开始使用 PHP AOT 编译器。
---
## 📦 前置要求
### 系统要求
- **操作系统**: Linux (推荐 Ubuntu 20.04+)
- **PHP 版本**: PHP 8.0+
- **编译器**: GCC 9.0+ 或 Clang 10.0+
- **内存**: 至少 2GB RAM
- **磁盘空间**: 至少 500MB
### 依赖安装
```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential php-cli php-dev clang-format
# CentOS/RHEL
sudo yum install -y gcc gcc-c++ php php-devel clang-tools-extra
```
---
## 🔧 安装步骤
### 1. 克隆项目
```bash
git clone https://github.com/your-org/php-aot-compiler.git
cd php-aot-compiler
```
### 2. 安装 Composer 依赖
```bash
composer install
```
### 3. 验证安装
```bash
php bin/compiler.php --help
```
如果看到帮助信息，说明安装成功！
---
## 🎯 基本使用
### 示例项目结构
假设我们有一个简单的 PHP 项目：
```
my-project/
├── src/
│ ├── Calculator.php
│ └── main.php
```
**Calculator.php**:
```php
<?php
class Calculator {
public function add($a, $b) {
return $a + $b;
}
public function multiply($a, $b) {
return $a * $b;
}
}
```
**main.php**:
```php
<?php
require_once 'Calculator.php';
function main() {
$calc = new Calculator();
echo "5 + 3 = " . $calc->add(5, 3) . "\n";
echo "4 * 7 = " . $calc->multiply(4, 7) . "\n";
}
```
---
## 📝 编译模式
### 模式一：二进制可执行文件（推荐新手）
#### 编译命令
```bash
php bin/compiler.php my-project/src/ -o my-app
```
#### 运行程序
```bash
./my-app
```
#### 输出
```
5 + 3 = 8
4 * 7 = 28
```
✅ **优点**:
- 独立运行，无需 PHP 环境
- 部署简单
- 性能更好
⚠️ **注意**: 必须包含 `main()` 函数
---
### 模式二：PHP 扩展
#### 编译命令
```bash
php bin/compiler.php my-project/src/ --mode=ext -o calculator
```
#### 安装扩展
```bash
# 复制 .so 文件到 PHP 扩展目录
sudo cp calculator.so $(php-config --extension-dir)/
# 在 php.ini 中添加
echo "extension=calculator" | sudo tee /etc/php/8.1/cli/conf.d/30-calculator.ini
```
#### 使用扩展
```bash
php -m | grep calculator # 验证扩展已加载
```
✅ **优点**:
- 与现有 PHP 项目集成
- 可以在 php-fpm 中使用
- 适合 Web 应用
⚠️ **注意**: 不需要 `main()` 函数
---
## 🎨 代码规范
### ✅ 正确的代码结构
```php
<?php
// 类和函数定义（允许在全局）
class MyClass {
public function doSomething() {
return "Something";
}
}
function helperFunction() {
return "Helper";
}
const MY_CONSTANT = 'value';
// 可执行代码必须在 main() 函数中
function main() {
$obj = new MyClass();
echo $obj->doSomething();
echo helperFunction();
echo MY_CONSTANT;
}
```
### ❌ 错误的代码结构
```php
<?php
// ❌ 游离的可执行代码（不允许）
echo "Hello World"; // 错误！
some_function_call(); // 错误！
for ($i = 0; $i < 10; $i++) { // 错误！
echo $i;
}
```
---
## 🧪 运行测试
### 运行单个测试
```bash
php run-tests.php --no-aot tests/aot/arrow-functions.phpt
```
### 运行所有测试
```bash
php run-tests.php --no-aot tests/aot/
```
### 查看测试结果
```
PASS Arrow Functions - PHP 8.1+ short closure syntax
FAIL Some test
=====================================================================
Number of tests : 100 100
Tests passed : 95 ( 95.0%)
Tests failed : 5 ( 5.0%)
```
---
## 💡 最佳实践
### 1. 项目组织
```
project/
├── src/ # 源代码
│ ├── Classes/ # 类文件
│ ├── Functions/ # 函数库
│ └── main.php # 入口文件
├── tests/ # 测试文件
└── build/ # 编译输出
```
### 2. 命名约定
- 文件名使用小写，单词间用下划线分隔：`my_class.php`
- 类名使用帕斯卡命名法：`MyClass`
- 函数名使用驼峰命名法：`myFunction`
### 3. 性能提示
- 避免不必要的对象创建
- 使用标量类型声明
- 减少全局变量使用
- 优先使用数组而非对象集合
---
## 🔍 常见问题
### Q: 编译失败，提示 "Not implemented"
**A**: 该语法特性暂不支持。查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解支持的语法。
### Q: 如何调试编译后的程序？
**A**: 使用 `--keep-all` 选项保留中间文件，查看生成的 C++ 代码。
```bash
php bin/compiler.php src/ -o app --keep-all
```
### Q: 编译速度慢怎么办？
**A**: 使用并行编译选项 `-j`：
```bash
php bin/compiler.php src/ -o app -j4 # 使用 4 个进程
```
---
## 📚 下一步
完成快速入门后，建议阅读：
1. **[语法支持规范](UNSUPPORTED_SYNTAX.md)** - 详细了解支持的语法
2. **[编译模式详解](COMPILATION_MODES.md)** - 深入了解两种编译模式
3. **[性能优化指南](PERFORMANCE.md)** - 提升程序性能
---
## 🆘 获取帮助
- 📖 查看完整文档：[docs/](.)
- 🐛 报告问题：[GitHub Issues]
- 💬 社区讨论：[论坛/聊天室链接]
---
**祝您使用愉快！** 🎉

192
docs/README.md
Unescape View File

@ -0,0 +1,192 @@
# PHP AOT 编译器文档索引
## 📚 文档概览
本文档集合为 PHP AOT (Ahead-Of-Time) 编译器提供完整的使用指南和技术参考。
---
## 📖 核心文档
### 1. [语法支持规范](UNSUPPORTED_SYNTAX.md)
**必读指数**: ⭐⭐⭐⭐⭐
详细说明：
- ✅ 已支持的 PHP 语法特性（50+ 个）
- ❌ 不支持的语法（7 种）
- ⏳ 计划支持的语法（2 种）
- 📊 编译模式对比表
- 💡 代码结构最佳实践
**适合人群**: 所有使用者
---
### 2. [快速入门指南](QUICKSTART.md)
**必读指数**: ⭐⭐⭐⭐⭐
内容概要：
- 🚀 5 分钟快速开始
- 📦 安装和配置
- 🔧 基本使用示例
- 🎯 第一个 AOT 编译项目
**适合人群**: 新手用户
---
### 3. [编译模式详解](COMPILATION_MODES.md)
**必读指数**: ⭐⭐⭐⭐
内容概要：
- 🔹 扩展模式（Extension Mode）
- 编译为 .so/.dll 文件
- 在 php-fpm 中加载
- Web 应用场景
- 🔸 二进制模式（Binary Mode）
- 编译为独立可执行文件
- main() 函数要求
- CLI 和服务端应用
**适合人群**: 开发者、架构师
---
### 4. [测试指南](TESTING_GUIDE.md)
**必读指数**: ⭐⭐⭐⭐
内容概要：
- 🧪 运行测试的方法
- 📝 编写 phpt 测试文件
- ✅ 测试规范和最佳实践
- 🔍 调试测试失败
- 📊 测试覆盖率分析
**适合人群**: 测试人员、贡献者
---
### 5. [性能优化指南](PERFORMANCE.md)
**必读指数**: ⭐⭐⭐
内容概要：
- ⚡ 编译优化选项
- 🎯 运行时性能调优
- 📈 基准测试方法
- 💾 内存管理策略
**适合人群**: 高级用户、性能工程师
---
### 6. [故障排除](TROUBLESHOOTING.md)
**必读指数**: ⭐⭐⭐⭐
内容概要：
- ❗ 常见错误和解决方案
- 🔧 调试技巧
- 💬 FAQ 常见问题
- 🆘 获取帮助
**适合人群**: 所有使用者
---
### 7. [架构设计](ARCHITECTURE.md)
**必读指数**: ⭐⭐⭐
内容概要：
- 🏗️ 编译器架构概述
- 📐 设计理念和原则
- 🔗 组件和模块说明
- 📊 数据流和工作流程
**适合人群**: 贡献者、研究者
---
### 8. [贡献指南](CONTRIBUTING.md)
**必读指数**: ⭐⭐⭐
内容概要：
- 🤝 如何贡献代码
- 📝 提交 PR 的流程
- 🎨 代码规范
- 🧪 测试要求
**适合人群**: 贡献者
---
## 🎯 快速导航
### 按使用场景
#### 我想开始使用 AOT 编译器
1. 阅读 [快速入门指南](QUICKSTART.md)
2. 查看 [语法支持规范](UNSUPPORTED_SYNTAX.md) 了解限制
3. 参考 [编译模式详解](COMPILATION_MODES.md) 选择模式
#### 我想运行测试
1. 阅读 [测试指南](TESTING_GUIDE.md)
2. 使用 `php run-tests.php --no-aot tests/aot/` 命令
3. 遇到问题查看 [故障排除](TROUBLESHOOTING.md)
#### 我想优化性能
1. 阅读 [性能优化指南](PERFORMANCE.md)
2. 查看基准测试结果
3. 应用优化建议
#### 我想贡献代码
1. 阅读 [贡献指南](CONTRIBUTING.md)
2. 了解 [架构设计](ARCHITECTURE.md)
3. Fork 项目并提交 PR
---
## 📋 文档维护
### 文档位置
- ✅ 所有 `.md` 文档必须放在 `docs/` 目录下
- ❌ 不要在其他目录创建文档文件
### 文档更新
- 保持文档与代码同步
- 重大变更需要更新相关文档
- 添加更新日期和版本信息
### 文档质量
- 使用清晰的标题和结构
- 包含代码示例
- 提供实际可运行的示例
- 使用中文编写（除非特殊需要）
---
## 🔗 外部资源
- **PHP 官方文档**: https://www.php.net/manual/en/
- **GitHub 仓库**: [项目地址]
- **问题追踪**: [Issue Tracker]
- **社区论坛**: [Community Forum]
---
## 📞 联系方式
- 技术支持：[support@example.com]
- 商务合作：[business@example.com]
- 社区讨论：[Slack/Discord 链接]
---
## 📜 许可证
本文档遵循 [MIT License](LICENSE)
---
**最后更新**: 2024 年 3 月 18 日
**文档版本**: v1.0
**适用版本**: PHP AOT Compiler v1.x

4
docs/UNSUPPORTED_SYNTAX.md
Unescape View File

@ -336,8 +336,8 @@ $b = std::float(3.1415926);
// 布尔类型 // 布尔类型
$c = std::bool(true); $c = std::bool(true);
// 字符串类型（如果支持） // ⚠️ 注意：目前仅支持以上 3 种原生类型
$d = std::string("hello"); // ❌ 不支持 std::string、std::array 等其他类型
``` ```
#### 类型约束规则 #### 类型约束规则

Write Preview
Loading…
Cancel
Save