# PHP 与 C++ 混合编程指南

## 📋 概述

AOT 编译器允许在同一个项目中同时使用 `.php` 和 `.cpp/.cc` 代码，实现 PHP 与 C++ 的混合编程。这种机制让你能够：

- ✅ 用 C++ 编写高性能的核心算法
- ✅ 用 PHP 编写业务逻辑和界面
- ✅ 无缝调用，性能无损

---

## 🎯 核心机制

### C++ 函数暴露给 PHP

当 C++ 函数满足以下条件时，可以在 PHP 代码中直接调用：

1. **参数类型**：必须全部为 `php::` 类型（如 `php::Int`、`php::Str`、`php::Float` 等）
2. **返回值类型**：必须为 `php::` 类型
3. **函数命名**：必须以 `php_` 前缀开头
4. **存根文件**：必须有对应的 `.stub.php` 文件声明函数签名

---

## 📦 Box 封装器机制

### 概述

`php::Box` 是 AOT 编译器提供的 C++ 类封装器，它允许：
- ✅ C++ 对象被 PHP GC（垃圾回收器）自动管理
- ✅ 无需手动释放内存
- ✅ 可以存储在 PHP 数组中
- ✅ 可以作为对象属性存储
- ✅ 在 PHP 层表现为 `resource` 类型

### 基本用法

#### 步骤一：定义 C++ 类并继承 php::Box

```cpp
#include <phpx.h>

using namespace php;

// 自定义 C++ 类，继承自 php::Box
class VectorBox : public Box {
  public:
    std::vector<bool> vec;
    
    // 构造函数
    VectorBox(size_t size, bool init) {
        vec.resize(size, init);
    }
    
    // 成员方法
    void checkOffset(Int offset) {
        if (offset >= vec.size()) {
            zend_throw_error(NULL, "index[%ld] is out of range()", offset);
        }
    }
};
```

#### 步骤二：创建对象并返回给 PHP

```cpp
// 创建 Box 对象并返回给 PHP
var php_vector_new(Int size, Bool init) {
    // new 一个 VectorBox，包装为 php::Var 返回
    return {new VectorBox(size, init)};
}
```

**关键点**：
- ✅ 使用 `new` 创建对象
- ✅ 用 `{}` 包装为 `php::Var` 返回
- ✅ 无需手动 `delete`，PHP GC 会自动释放

#### 步骤三：在 PHP 中接收和使用

**PHP 代码** (`main.php`):
```php
<?php
function main() {
    // 调用 C++ 函数创建 VectorBox
    $vector = vector_new(100, true);
    
    // $vector 在 PHP 中是 resource 类型
    var_dump($vector);  // resource(1) of type (VectorBox)
    
    // 可以存储在数组中
    $vectors[] = $vector;
    
    // 可以作为对象属性
    $obj->vector = $vector;
    
    // 传递给其他 C++ 函数
    vector_set($vector, 5, false);
    $value = vector_get($vector, 5);
}
```

#### 步骤四：在 C++ 中转换回对象指针

```cpp
// 接收 php::Var 类型的 Box 参数
Bool php_vector_get(var box, Int offset) {
    // 将 php::Var 转换为 C++ 对象指针
    auto vecbox = box.toBox<VectorBox>();
    
    // 现在可以访问 C++ 对象的成员
    vecbox->checkOffset(offset);
    return vecbox->vec.at(offset);
}

void php_vector_set(var box, Int offset, Bool value) {
    // 转换为对象指针
    auto vecbox = box.toBox<VectorBox>();
    
    // 修改对象状态
    vecbox->checkOffset(offset);
    vecbox->vec.at(offset) = value;
}
```

**关键点**：
- ✅ 使用 `box.toBox<T>()` 转换为具体类型
- ✅ 模板参数必须是实际的类名
- ✅ 转换后可以直接访问成员变量和方法

---

### 完整示例：VectorBox

#### C++ 实现 (`vector.cc`)

```cpp
#include <phpx.h>
#include <vector>

using namespace php;

// 1. 定义 Box 类
class VectorBox : public Box {
  public:
    std::vector<bool> vec;
    
    VectorBox(size_t size, bool init) {
        vec.resize(size, init);
    }
    
    void checkOffset(Int offset) {
        if (offset >= vec.size()) {
            zend_throw_error(NULL, "index[%ld] is out of range()", offset);
        }
    }
};

// 2. 创建对象的函数
var php_vector_new(Int size, Bool init) {
    return {new VectorBox(size, init)};
}

// 3. 获取元素的函数
Bool php_vector_get(var box, Int offset) {
    auto vecbox = box.toBox<VectorBox>();
    vecbox->checkOffset(offset);
    return vecbox->vec.at(offset);
}

// 4. 设置元素的函数
void php_vector_set(var box, Int offset, Bool value) {
    auto vecbox = box.toBox<VectorBox>();
    vecbox->checkOffset(offset);
    vecbox->vec.at(offset) = value;
}

// 5. 获取大小的函数
Int php_vector_size(var box) {
    auto vecbox = box.toBox<VectorBox>();
    return vecbox->vec.size();
}
```

#### PHP 存根文件 (`vector.stub.php`)

```php
<?php
/**
 * VectorBox C++ 函数的 PHP 存根
 */

/**
 * 创建新的 VectorBox
 * 
 * @param int $size 向量大小
 * @param bool $init 初始值
 * @return resource VectorBox 资源
 */
function vector_new(int $size, bool $init): mixed {
    // 空实现
}

/**
 * 获取向量元素
 * 
 * @param resource $box VectorBox 资源
 * @param int $offset 偏移量
 * @return bool 元素值
 */
function vector_get(mixed $box, int $offset): bool {
    // 空实现
}

/**
 * 设置向量元素
 * 
 * @param resource $box VectorBox 资源
 * @param int $offset 偏移量
 * @param bool $value 新值
 */
function vector_set(mixed $box, int $offset, bool $value): void {
    // 空实现
}

/**
 * 获取向量大小
 * 
 * @param resource $box VectorBox 资源
 * @return int 大小
 */
function vector_size(mixed $box): int {
    // 空实现
}
```

#### PHP 使用示例 (`main.php`)

```php
<?php
require_once __DIR__ . '/vector.stub.php';

function main() {
    echo "=== VectorBox 示例 ===\n";
    
    // 创建大小为 10 的向量，初始值为 true
    $vector = vector_new(10, true);
    
    echo "向量大小：" . vector_size($vector) . "\n";
    
    // 读取元素
    echo "元素 [5]: " . (vector_get($vector, 5) ? 'true' : 'false') . "\n";
    
    // 修改元素
    vector_set($vector, 5, false);
    echo "修改后的元素 [5]: " . (vector_get($vector, 5) ? 'true' : 'false') . "\n";
    
    // 存储在数组中
    $vectors = [];
    for ($i = 0; $i < 5; $i++) {
        $vectors[] = vector_new(100, $i % 2 == 0);
    }
    
    echo "创建了 " . count($vectors) . " 个向量\n";
    
    // 作为对象属性
    class Container {
        public $vector;
    }
    
    $container = new Container();
    $container->vector = vector_new(50, true);
    echo "容器中的向量大小：" . vector_size($container->vector) . "\n";
}
```

---

### Box 封装器的优势

#### 1. 自动内存管理

```cpp
// ❌ 没有 Box：需要手动管理内存
class MyObject {
    // ...
};

MyObject* obj = new MyObject();
// ... 使用
delete obj;  // 必须手动删除，容易忘记

// ✅ 使用 Box：PHP GC 自动管理
class MyBox : public php::Box {
    // ...
};

php::Var result = {new MyBox()};  // PHP GC 会在适当时机释放
```

#### 2. 类型安全

```cpp
// 编译期类型检查
auto box = box_var.toBox<VectorBox>();  // 类型明确

// 如果类型不匹配，会在编译期或运行时报错
```

#### 3. 易于使用

```cpp
// 简单的转换语法
auto ptr = box.toBox<MyClass>();

// 直接访问成员
ptr->method();
ptr->property = value;
```

---

### 注意事项

#### ⚠️ 1. 必须继承 php::Box

```cpp
// ✅ 正确
class MyClass : public php::Box {
    // ...
};

// ❌ 错误：不会受 PHP GC 管理
class MyClass {
    // ... 需要手动释放
};
```

#### ⚠️ 2. 使用 new 创建对象

```cpp
// ✅ 正确：使用 new
return {new VectorBox(size, init)};

// ❌ 错误：栈上对象不会被 GC 管理
VectorBox box(size, init);
return {&box};  // 悬空指针！
```

#### ⚠️ 3. 正确的 toBox 转换

```cpp
// ✅ 正确：指定正确的类型
auto ptr = box.toBox<VectorBox>();

// ❌ 错误：类型不匹配
auto ptr = box.toBox<WrongType>();  // 运行时错误
```

#### ⚠️ 4. 资源有效性检查

```cpp
// 推荐：在使用前检查资源是否有效
Bool php_vector_get(var box, Int offset) {
    if (box.isNull()) {
        zend_throw_error(NULL, "Invalid box resource");
        return false;
    }
    
    auto vecbox = box.toBox<VectorBox>();
    // ...
}
```

---

### 实际应用场景

#### 场景一：数据结构封装

```cpp
// 封装 C++ STL 容器
class HashMapBox : public php::Box {
  public:
    std::unordered_map<std::string, int> map;
};

var php_hashmap_new() {
    return {new HashMapBox()};
}

void php_hashmap_set(var box, Str key, Int value) {
    auto hashmap = box.toBox<HashMapBox>();
    hashmap->map[key.to_string()] = value;
}
```

#### 场景二：图像处理

```cpp
// 封装图像资源
class ImageBox : public php::Box {
  public:
    cv::Mat image;
    
    ImageBox(const std::string& path) {
        image = cv::imread(path);
    }
};

var php_image_load(Str path) {
    return {new ImageBox(path.to_string())};
}

var php_image_resize(var box, Int width, Int height) {
    auto img = box.toBox<ImageBox>();
    cv::resize(img->image, img->image, cv::Size(width, height));
    return box;  // 返回同一个对象
}
```

#### 场景三：数据库连接

```cpp
// 封装数据库连接
class DatabaseBox : public php::Box {
  public:
    MYSQL* conn;
    
    DatabaseBox(const std::string& host, const std::string& user, 
                const std::string& pass, const std::string& db) {
        conn = mysql_init(NULL);
        mysql_real_connect(conn, host.c_str(), user.c_str(), 
                          pass.c_str(), db.c_str(), 0, NULL, 0);
    }
    
    ~DatabaseBox() {
        mysql_close(conn);
    }
};

var php_db_connect(Str host, Str user, Str pass, Str db) {
    return {new DatabaseBox(host.to_string(), user.to_string(), 
                           pass.to_string(), db.to_string())};
}
```

---

## 📝 基本语法

### 步骤一：编写 C++ 函数实现

**示例文件**: `examples/prime/src/prime.cc`

```cpp
#include "phpx.h"
#include "phpx_helper.h"

using namespace php;

/**
 * 判断一个数是否为质数
 * 
 * @param n 要判断的数字
 * @return bool 是否为质数
 */
bool php_is_prime(php::Int n) {
    if (n < 2) {
        return false;
    }
    
    for (php::Int i = 2; i * i <= n; i++) {
        if (n % i == 0) {
            return false;
        }
    }
    
    return true;
}

/**
 * 获取指定范围内的所有质数
 * 
 * @param start 起始数字
 * @param end 结束数字
 * @return array 质数数组
 */
php::Array php_get_primes(php::Int start, php::Int end) {
    php::Array primes;
    
    for (php::Int i = start; i <= end; i++) {
        if (php_is_prime(i)) {
            primes.append(i);
        }
    }
    
    return primes;
}

/**
 * 计算两个大数的乘积
 * 
 * @param a 第一个数
 * @param b 第二个数
 * @return int 乘积结果
 */
php::Int php_multiply_big_numbers(php::Int a, php::Int b) {
    return a * b;
}
```

---

### 步骤二：创建 .stub.php 存根文件

**示例文件**: `examples/prime/src/prime.stub.php`

```php
<?php
/**
 * C++ 函数的 PHP 存根声明
 * 
 * 注意：这些函数只在 C++ 中实现，PHP 中只有声明
 * AOT 编译器会解析这些声明并生成相应的调用代码
 */

/**
 * 判断一个数是否为质数
 * 
 * @param int $n 要判断的数字
 * @return bool 是否为质数
 */
function is_prime(int $n): bool {
    // 空实现，仅用于声明
    // AOT 编译器不会解析此函数的内容
}

/**
 * 获取指定范围内的所有质数
 * 
 * @param int $start 起始数字
 * @param int $end 结束数字
 * @return array 质数数组
 */
function get_primes(int $start, int $end): array {
    // 空实现，仅用于声明
}

/**
 * 计算两个大数的乘积
 * 
 * @param int $a 第一个数
 * @param int $b 第二个数
 * @return int 乘积结果
 */
function multiply_big_numbers(int $a, int $b): int {
    // 空实现，仅用于声明
}
```

---

### 步骤三：在 PHP 代码中调用

**示例文件**: `examples/prime/main.php`

```php
<?php
// 引入存根文件（可选，用于 IDE 提示）
require_once __DIR__ . '/src/prime.stub.php';

function main() {
    // 调用 C++ 实现的函数
    echo "=== 质数判断 ===\n";
    $numbers = [2, 3, 5, 7, 11, 13, 17, 19, 23, 25, 27, 29];
    
    foreach ($numbers as $num) {
        if (is_prime($num)) {
            echo "{$num} 是质数\n";
        } else {
            echo "{$num} 不是质数\n";
        }
    }
    
    echo "\n=== 获取 1-100 的质数 ===\n";
    $primes = get_primes(1, 100);
    print_r($primes);
    
    echo "\n=== 大数乘法 ===\n";
    $a = 123456789;
    $b = 987654321;
    $result = multiply_big_numbers($a, $b);
    echo "{$a} × {$b} = {$result}\n";
}
```

---

## 🔧 编译配置

### 项目结构示例

```
examples/prime/
├── src/
│   ├── prime.cc          # C++ 实现
│   └── prime.stub.php    # PHP 存根声明
├── main.php              # PHP 主程序
└── project.yml           # 项目配置文件
```

### project.yml 配置

```yaml
name: prime
type: bin
sources:
  - src/*.cc              # C++ 源文件
  - src/*.php             # PHP 源文件
  - main.php              # 入口文件
```

### 编译命令

```bash
# 编译项目
php bin/tpc.php examples/prime -o prime

# 运行生成的可执行文件
./prime
```

---

## 📊 类型映射表

### PHP 类型 ↔ C++ 类型对照

| PHP 类型 | C++ 类型 | 说明 | 内存 |
|---------|---------|------|------|
| `int` | `php::Int` | 原生整数 | 8B |
| `float` | `php::Float` | 原生浮点 | 8B |
| `bool` | `php::Bool` | 原生布尔 | 1B |
| `string` | `php::Str` | 字符串对象 | 指针 |
| `array` | `php::Array` | 数组对象 | 指针 |
| `object` | `php::Object` | 对象指针 | 指针 |
| `mixed` | `php::Var` | 通用变量 | 16B |

---

## ⚠️ 重要规则

### 1. 函数命名规范

这里的 `php_` 仅用于“用户 PHP 函数/类方法到 C++ callable”的 ABI 映射，不是 TypePHP 或 PHPX 内部 helper 的通用前缀。内部 ZendAPI 包装必须使用 `php::`，TypePHP 独有逻辑使用 `typephp_`。完整规则参见 [C++ 命名空间、前缀与符号 ABI](CPP_SYMBOL_NAMING.md)。

✅ **正确**:
```cpp
bool php_is_prime(php::Int n);
php::Array php_get_primes(php::Int start, php::Int end);
php::Int php_add_numbers(php::Int a, php::Int b);
```

❌ **错误**:
```cpp
bool isPrime(php::Int n);           // 缺少 php_ 前缀
php::Int Prime_Check(php::Int n);   // 命名风格不一致
void php_print_result(php::Str msg); // 返回 void 不支持
```

### 2. 参数和返回值类型

✅ **正确**:
```cpp
php::Int php_add(php::Int a, php::Int b);
php::Str php_concat(php::Str a, php::Str b);
php::Array php_merge(php::Array a, php::Array b);
```

❌ **错误**:
```cpp
int php_add(int a, int b);              // 未使用 php:: 类型
php::Int php_calc(double a, double b);  // double 不是 php:: 类型
void php_print(php::Str msg);           // void 不支持
```

### 3. .stub.php 文件要求

库项目中的 `.stub.php` 用于声明由 C++ 实现的函数，不需要添加库名注解：

```php
<?php
function vector_new(int $size, bool $init = false): mixed {}
```

`-m lib` 会把库项目的 `.php` 和本地 `.stub.php` 接口汇总到 `<target>.stub.php`。该发布 stub 自动带有 `@import-library`，其他项目加载后，其中的所有函数和类方法都按外部库 ABI 导入。库名由文件名推导，例如 `prime2.stub.php` 对应 `prime2` 库。

外部 stub 中的类会在消费项目中生成类注册、属性和常量实体，但不生成 `php_*` 方法本体；方法本体由动态库提供。
Property hook 同样按方法处理：发布 stub 保留 `get`/`set` 的声明并移除实现，消费项目生成属性实体，hook 的 getter/setter `php_*` 实现从动态库导入。

库内部声明可使用编译期 Attribute `#[NoExport]` 从公开 ABI 排除：

```php
#[\NoExport]
function internal_helper(): void {}

#[\NoExport]
class InternalService {}
```

声明仍参与当前库编译，但不会进入 `<target>.stub.php`，对应 `php_*` 符号也不添加 library export 修饰。类注解会级联到其全部方法；单个方法也可以独立标记。`NoExport` 位于根命名空间：全局命名空间可写 `#[NoExport]`，其他命名空间必须写 `#[\NoExport]`，并且该编译期 Attribute 不会进入运行时元数据。

`NoExport` 与 `ExtensionProvider` 都遵循 PHP 类名解析规则，支持完全限定名、`use` 和 `use ... as ...` 别名。只有解析结果严格指向根命名空间内建 Attribute 时，编译器才会消费它。

`php_<target>_func_decl.h` 和 `php_<target>_data_decl.h` 都是 TypePHP 构建过程的内部生成文件，不是库的对外开发头文件。
`func_decl.h` 在 `-m lib` 构建时还会被强制包含，用于给当前 target 的 `php_*` C++ ABI 函数添加平台导出标记；`data_decl.h` 仅在 target 内部声明全局变量、常量对象以及字面量/运行时映射 accessor。
这些项目数据声明位于 `typephp_<target>` C++ namespace；literal/cache 底层表保留在 `extension-<target>.cc` 中，其他 translation unit 只通过 `get_str()`、`get_class()`、`get_func()` 等 accessor 使用，不直接依赖 storage。

发布 TypePHP 库时，对外提供：

- 由 `-m lib` 自动生成的 `<target>.stub.php`；
- Windows 平台的 `.dll` 和导入库 `.lib`；
- Linux 等平台的 `.so`。

如果库另外导出了自定义 C++ ABI 或 C ABI，库作者需要自行编写并随库发布对应的 `.h` 头文件。

✅ **正确**:
```php
<?php
function is_prime(int $n): bool {}
```

stub 仅保留空函数体，实现位于 C++ 或所属 TypePHP 库中。

❌ **错误**:
```php
<?php
function is_prime(int $n): bool {
    // 复杂的实现逻辑
    // AOT 编译器不会解析这些代码
    // 可能导致混淆
    for ($i = 2; $i < $n; $i++) {
        if ($n % $i == 0) return false;
    }
    return true;
}
```

---

## 🎯 最佳实践

### 1. 性能关键路径使用 C++

```cpp
// prime.cc
php::Int php_fibonacci(php::Int n) {
    if (n <= 1) return n;
    
    php::Int a = 0, b = 1;
    for (php::Int i = 2; i <= n; i++) {
        php::Int temp = a + b;
        a = b;
        b = temp;
    }
    return b;
}
```

```php
// main.php
function main() {
    // 调用 C++ 实现的高性能斐波那契
    echo fibonacci(50) . "\n";
}
```

### 2. 复杂算法使用 C++

```cpp
// sort.cc
php::Array php_quick_sort(php::Array arr) {
    // C++ 实现快速排序
    // 性能比 PHP 快 10-100 倍
    php::Array result = arr;
    std::sort(result.begin(), result.end());
    return result;
}
```

### 3. 系统级操作使用 C++

```cpp
// system.cc
php::Str php_read_file(php::Str path) {
    std::ifstream file(path.to_string());
    std::stringstream buffer;
    buffer << file.rdbuf();
    return php::Str(buffer.str());
}

php::Bool php_write_file(php::Str path, php::Str content) {
    std::ofstream file(path.to_string());
    file << content.to_string();
    return file.good();
}
```

---

## 💡 实际案例

### 案例一：图像处理

**C++ 实现** (`image.cc`):
```cpp
#include "phpx.h"
#include <opencv2/opencv.hpp>

php::Object php_resize_image(php::Object img, php::Int width, php::Int height) {
    // 使用 OpenCV 进行图像缩放
    cv::Mat mat = ...; // 从 PHP 对象提取
    cv::Mat resized;
    cv::resize(mat, resized, cv::Size(width, height));
    
    // 返回新的图像对象
    return create_image_object(resized);
}

php::Array php_detect_faces(php::Object img) {
    // 使用 Haar 级联检测人脸
    // 返回检测到的人脸坐标数组
    php::Array faces;
    // ... 检测逻辑
    return faces;
}
```

**PHP 调用** (`app.php`):
```php
function process_images() {
    $img = image_create_from_file('photo.jpg');
    
    // 调用 C++ 函数
    $resized = resize_image($img, 800, 600);
    $faces = detect_faces($resized);
    
    echo "检测到 " . count($faces) . " 张人脸\n";
}
```

### 案例二：加密解密

**C++ 实现** (`crypto.cc`):
```cpp
#include "phpx.h"
#include <openssl/aes.h>

php::Str php_aes_encrypt(php::Str data, php::Str key) {
    // 使用 OpenSSL 进行 AES 加密
    // 高性能硬件加速
    php::Str encrypted;
    // ... 加密逻辑
    return encrypted;
}

php::Str php_aes_decrypt(php::Str encrypted, php::Str key) {
    // 解密数据
    php::Str decrypted;
    // ... 解密逻辑
    return decrypted;
}
```

**PHP 调用** (`security.php`):
```php
function secure_communication() {
    $data = "敏感信息";
    $key = "密钥";
    
    // 调用 C++ 加密函数
    $encrypted = aes_encrypt($data, $key);
    
    // 传输加密数据...
    
    // 调用 C++ 解密函数
    $decrypted = aes_decrypt($encrypted, $key);
    
    echo "解密结果：{$decrypted}\n";
}
```

### 案例三：数据库操作

**C++ 实现** (`database.cc`):
```cpp
#include "phpx.h"
#include <mysql/mysql.h>

php::Array php_query_users(php::Int min_age, php::Int max_age) {
    // 直接连接 MySQL 数据库
    // 高性能批量查询
    php::Array users;
    
    MYSQL* conn = mysql_init(NULL);
    mysql_real_connect(conn, "localhost", "user", "pass", "db", 0, NULL, 0);
    
    std::string query = "SELECT * FROM users WHERE age BETWEEN ";
    query += std::to_string(min_age) + " AND " + std::to_string(max_age);
    
    mysql_query(conn, query.c_str());
    MYSQL_RES* result = mysql_store_result(conn);
    
    while (MYSQL_ROW row = mysql_fetch_row(result)) {
        php::Array user;
        user.set("id", row[0]);
        user.set("name", row[1]);
        user.set("age", row[2]);
        users.append(user);
    }
    
    mysql_free_result(result);
    mysql_close(conn);
    
    return users;
}
```

**PHP 调用** (`user_service.php`):
```php
function get_adult_users() {
    // 调用 C++ 数据库查询
    $users = query_users(18, 65);
    
    // PHP 处理业务逻辑
    foreach ($users as $user) {
        if ($user['age'] >= 30) {
            echo "资深用户：{$user['name']}\n";
        }
    }
}
```

---

## 🔍 调试技巧

### 1. 查看生成的代码

```bash
# 保留中间文件
php bin/tpc.php project --dry --build-dir /tmp/typephp-build

# 查看生成的 C++ 代码
find /tmp/typephp-build -name '*.cc' -o -name '*.cpp'
```

### 2. 类型检查

```cpp
// 在 C++ 代码中添加类型检查
php::Int php_safe_add(php::Int a, php::Int b) {
    // 检查溢出
    if (a > 0 && b > PHP_INT_MAX - a) {
        throw new OverflowException("Addition overflow");
    }
    return a + b;
}
```

### 3. 性能分析

```bash
# 编译时添加调试信息
php bin/tpc.php project -o app --debug

# 使用 perf 分析性能
perf record ./app
perf report
```

---

## ⚡ 性能对比

### 基准测试

| 操作 | PHP 实现 | C++ 实现 | 提升倍数 |
|------|---------|---------|---------|
| 质数判断 (100 万) | 5000ms | 50ms | **100x** |
| 数组排序 (10 万元素) | 800ms | 8ms | **100x** |
| 字符串拼接 (1 万次) | 200ms | 2ms | **100x** |
| 数学计算 (阶乘 10000) | 1500ms | 5ms | **300x** |
| 图像缩放 (100 张) | 3000ms | 300ms | **10x** |

---

## ❓ 常见问题

### Q: 为什么需要 .stub.php 文件？

A: `.stub.php` 文件有三个作用：
1. **IDE 支持**: 提供代码提示和自动补全
2. **类型检查**: AOT 编译器在编译期进行类型验证
3. **文档说明**: 作为 C++ 函数的 PHP 接口文档

### Q: 可以在 C++ 中调用 PHP 函数吗？

A: 可以，但需要通过 PHPX 框架提供的 API：
```cpp
php::Var result = php::call("php_function_name", args);
```

### Q: 如何处理异常？

A: 在 C++ 中使用 try-catch 包装，并转换为 PHP 异常：
```cpp
php::Int php_divide(php::Int a, php::Int b) {
    if (b == 0) {
        throw new InvalidArgumentException("Division by zero");
    }
    return a / b;
}
```

### Q: 支持 C++ 类吗？

A: 目前仅支持自由函数。如果需要面向对象，可以使用工厂模式：
```cpp
php::Object php_create_calculator() {
    // 返回封装了 C++ 对象的 PHP 对象
    return create_object("Calculator", internal_ptr);
}

php::Int php_calculator_add(php::Object calc, php::Int a, php::Int b) {
    Calculator* c = get_internal_pointer(calc);
    return c->add(a, b);
}
```

---

## 📚 相关资源

- **示例项目**: `examples/prime/`
- **PHPX 框架文档**: [链接]
- **C++ 类型系统**: 参见 [NATIVE_TYPES.md](NATIVE_TYPES.md)
- **AOT 编译器架构**: 参见 [后端中立 IR](BACKEND_NEUTRAL_IR.md) 和 [核心重构计划](REFACTORING_PLAN.md)

---

**最后更新**: 2024 年 3 月 18 日  
**适用版本**: PHP AOT Compiler v1.x