|
|
# 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
|
|
|
|
