# typephp-doc

**Repository Path**: chenbool/typephp-doc

## Basic Information

- **Project Name**: typephp-doc
- **Description**: typephp-doc
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Webman TypePHP AOT 二进制构建插件

> **一句话**：将 PHP 代码编译为独立二进制，零依赖部署

---

## 📑 目录

- [是什么](#-是什么)
- [为什么用](#-为什么用)
- [快速开始](#-快速开始)
- [配置文件](#-配置文件)
- [产物结构](#-产物结构)
- [优化建议](#-优化建议)
- [常见问题](#-常见问题)
- [适用场景](#-适用场景)
- [工作流](#-工作流)
- [相关链接](#-相关链接)

---

## 🔍 是什么

**tinywan/webman-typephp** — Webman 生态的 TypePHP AOT 构建插件。

| 功能 | 说明 |
|------|------|
| 自动生成 | AOT 入口文件 + Linux 编译配置 |
| Docker 构建 | 使用 Builder 镜像完成编译 |
| 输出产物 | `dist/` 目录，直接部署到 Linux |

**原理**：业务代码仍用 PHP 开发，插件自动处理框架补丁，TypePHP AOT 编译为原生 ELF 二进制，无法编译的逻辑保留 Zend 兼容链路。

---

## 💡 为什么用

| 痛点 | 方案 |
|------|------|
| 服务器需装 PHP | 编译为独立二进制，零依赖 |
| 源码泄露风险 | AOT 编译为机器码 |
| 环境不一致 | Docker 构建，产物一致 |
| 编译工具链复杂 | 宿主机只需 PHP + Composer + Docker |

---

## 🚀 快速开始

### 前置条件

| 环境 | 要求 | 检查命令 |
|------|------|----------|
| PHP | ≥ 8.0 | `php -v` |
| Composer | 已安装 | `composer -V` |
| Docker | 已启动 | `docker --version` |

---

### 第 1 步：安装插件

**在 Webman 项目根目录执行**：

```bash
composer require tinywan/webman-typephp --dev
```

**执行过程**：

```
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 1 install, 0 updates, 0 updates
  - Installing tinywan/webman-typephp (v0.1.0): Downloading (100%)
Writing lock file
Generating autoload files
```

**安装后变化**：

| 变化 | 说明 |
|------|------|
| `vendor/tinywan/webman-typephp/` | 插件代码 |
| `config/plugin/tinywan/typephp/app.php` | 配置文件 |
| `composer.json` | 新增 `tinywan/webman-typephp` 依赖 |

**验证安装**：

```bash
php webman typephp:doctor
```

---

### 第 2 步：环境预检

**执行命令**：

```bash
php webman typephp:doctor
```

**预期输出**：

```
=== TypePHP Environment Diagnostic Tool ===

• PHP Version: 8.5.10 [OK]
• Docker: Docker version 29.7.2, build a7dcaa6 [OK - Required for Phase 1]
• Host Clang Compiler: Not installed [OK - Handled inside Docker builder]
```

**检查项说明**：

| 检查项 | 状态 | 说明 |
|--------|------|------|
| PHP Version | [OK] | 版本 ≥ 8.0 即可 |
| Docker | [OK] | 必须运行，用于构建 |
| Host Clang | [OK] | 无需安装，Docker 内已内置 |

**如果 Docker 报错**：

```bash
# 启动 Docker 服务（Windows）
# 1. 打开 Docker Desktop
# 2. 确保状态为 "Running"

# 或检查 Docker 是否启动
docker info
```

---

### 第 3 步：编译打包

#### 3.1 默认打包

```bash
php webman typephp:package
```

**执行过程**：

```
[TypePHP] Preparing build files for Webman project...

[1/3] Verified AOT entrypoint: main.php
[2/3] Generated compiler config: project.linux.yml
[2/3] Generated flattened AOT sources: .typephp/build/helpers.php
[2/3] Generated nullable-static AOT sources: .typephp/build/coroutine-context.php
[3/3] Running TypePHP AOT compilation container...

[INFO] Compiling Linux x86_64 glibc binary (job=8)...
[Scanning 12/51] app ...
[Scanning 51/51] vendor/monolog/monolog/src/Monolog/Processor ...
[Analyzing 1/173] 1% /native/20260907T074248Z-1/main.php
[129/129] 100% native/20260907T074248Z-1/.typephp/build/fast-route-functions.cc

Successfully compiled 129 files
g++ build/webman_server.rsp -o build/webman_server -lphpx -lphp

Build successful: build/webman_server
[SUCCESS] Portable directory created: dist
```

**输出目录**：`dist/`

#### 3.2 强制覆盖

```bash
php webman typephp:package --force
```

**作用**：自动备份旧 `dist/` 目录为 `dist_backup_时间戳/`，再重新构建。

#### 3.3 刷新入口文件

```bash
php webman typephp:package --refresh-main
```

**作用**：重新生成 `main.php` 入口文件，旧文件自动备份。

#### 3.4 指定自定义镜像

```bash
php webman typephp:package --image=tinywan/typephp-webman-builder:v0.1.0
```

**适用场景**：官方镜像有 bug 或需要自定义构建环境时。

---

### 第 4 步：部署启动

#### 4.1 上传到服务器

```bash
# 将 dist/ 目录上传到 Linux 服务器
# 方式一：scp
scp -r dist/ user@server:/opt/

# 方式二：tar 压缩后上传
tar czf dist.tar.gz dist/
scp dist.tar.gz user@server:/opt/
```

#### 4.2 服务器环境检查

```bash
# 检查 glibc 版本（需 ≥ 2.17）
ldd --version

# 检查系统架构（需 x86_64）
uname -m
```

#### 4.3 启动服务

```bash
cd /opt/dist

# 前台启动（调试用）
./start.sh start

# 后台启动（生产用）
./start.sh start -d
```

#### 4.4 常用命令

```bash
./start.sh status      # 查看运行状态
./start.sh stop        # 停止服务
./start.sh restart     # 重启服务
./webman-server start  # 直接启动二进制
```

#### 4.5 验证运行

```bash
# 查看进程
ps aux | grep webman

# 查看端口
netstat -tlnp | grep :8080

# 访问服务
curl http://localhost:8080
```

---

## ⚙️ 配置文件

**路径**：`config/plugin/tinywan/typephp/app.php`

```php
return [
    'enable' => true,
    'docker' => [
        'enabled' => true,
        'image' => 'tinywan/typephp-webman-builder:v0.1.0',
    ],
    'build' => [
        'output_name' => 'webman-server',
        'dist_dir' => 'dist',
        'clean_build' => true,
    ],
];
```

| 选项 | 默认 | 说明 |
|------|------|------|
| `enable` | true | 启用插件 |
| `docker.enabled` | true | 是否使用 Docker 构建 |
| `docker.image` | v0.1.0 | 构建镜像版本 |
| `build.output_name` | webman-server | 二进制名称 |
| `build.dist_dir` | dist | 输出目录 |
| `build.clean_build` | true | 清理缓存（建议关闭提速） |

---

## 📦 产物结构

```
dist/
├── webman-server.bin   # 原生 ELF 二进制（编译产物）
├── webman-server       # 启动包装脚本
├── start.sh            # Workerman 标准启停脚本
├── libphp.so           # PHP 运行时共享库
├── libphpx.so          # PHPX 运行时共享库
├── php.ini             # 独立 PHP 配置
├── ext/                # PHP 扩展 so 文件
├── lib/                # 系统依赖库
├── runtime/            # 日志、缓存目录
├── build-manifest.json # 构建元信息
├── config/             # 业务配置
├── public/             # 静态资源
└── app/view/           # 视图模板
```

**说明**：`lib/` 携带编译所需全部动态依赖；glibc 与系统加载器由目标服务器提供。

---

## 🛠️ 优化建议

| 优化项 | 操作 | 效果 |
|--------|------|------|
| 构建速度 | `clean_build` → `false` | 提速 40-60% |
| 镜像锁定 | 固定版本 `v0.1.0` | 避免兼容问题 |
| 产物瘦身 | `strip webman-server.bin` | 减体积 30-50% |
| 部署检查 | `ldd --version ≥ 2.17` | 避免 glibc 错误 |

---

## ❓ 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| `docker: permission denied` | 无 docker 权限 | `sudo usermod -aG docker $USER` |
| `glibc version too old` | glibc < 2.17 | 升级系统或用 alpine |
| `Segmentation fault` | 扩展不兼容 | 检查 `ext/` 目录 |
| `php.ini not found` | 路径错误 | 确认 `dist/php.ini` 存在 |

---

## 🎯 适用场景

| 场景 | 推荐度 | 说明 |
|------|--------|------|
| CPU 密集型 | ⭐⭐⭐⭐⭐ | 原生机器码，性能提升显著 |
| API 网关/微服务 | ⭐⭐⭐⭐ | 启动快、内存低 |
| 传统 Web 业务 | ⭐⭐⭐ | IO 密集型，收益有限 |
| 源码保护 | ⭐⭐⭐⭐⭐ | 反编译难度极大 |

---

## 📊 性能对比

> 数据来源：TypePHP 官方基准测试（PHP 8.5，-O3 优化，同机器对比）

### 语言基准（PHP 官方 bench.php）

| 基准测试 | 解释执行 PHP | TypePHP AOT | 提升倍数 |
|----------|-------------|-------------|---------|
| `bench.php` | 5.034 s | **0.603 s** | **~8×** |
| `micro_bench.php` | 13.045 s | **2.021 s** | **~6.5×** |

**测试内容**：函数调用、对象属性访问、数组/哈希操作、字符串处理、控制流等核心语言特性。

### 容器性能（10000×100000 元素更新循环）

| 实现方式 | 耗时 |
|----------|------|
| PHP 数组（JIT） | 67.6 s |
| `std::array`（TypePHP AOT） | **6.4 s** |
| C++ `std::vector` | 6.2 s |

**结论**：TypePHP 的 `std::array` 比 PHP 数组快 **~10×**，接近手写 C++ 性能。

### 性能提升总结

| 场景 | 提升幅度 | 原因 |
|------|----------|------|
| CPU 密集型计算 | **6-8×** | 原生机器码，无 ZendVM 解释开销 |
| 数组/容器操作 | **~10×** | 编译为 C++ 原生容器，无哈希表开销 |
| 数值计算 | **显著** | `int`/`float` 直接映射 C++ 类型 |
| IO 密集型 Web | **有限** | 瓶颈在网络/磁盘，非 CPU |

> ⚠️ 注意：以上为官方基准数据，实际提升因业务而异。建议在相同机器、相同负载下实测。

---

## 🔄 工作流

```
开发 → 常规 PHP 调试
  ↓
测试 → typephp:package --force
  ↓
预发布 → 验证 dist/ 运行
  ↓
生产 → 上传 dist/，start.sh start -d
```

---

## 🔗 相关链接

- 官方文档：https://swoole.com/aot/zh
- 项目仓库：https://github.com/Tinywan/webman-typephp
- 问题反馈：https://github.com/Tinywan/webman-typephp/issues