嘎挝偶荷集成特性
架构
这个集成分三层：
C 层（nxt_php_sapi.c, nxt_php_extension.c）
在 PHP 里注册 TrueAsync SAPI
给每个请求创建协程
通过 nxt_unit_run() 管理事件循环
通过 nxt_unit_response_write_nb() 实现非阻塞数据传输
PHP 扩展层（NginxUnit 命名空间）
NginxUnit\Request - 请求对象
NginxUnit\Response - 响应对象，支持非阻塞发送
NginxUnit\HttpServer::onRequest() - 注册请求处理器
用户代码（entrypoint.php）
通过 HttpServer::onRequest() 注册处理器
使用 Request/Response API
完全异步执行
请求流程
HTTP 请求 → NGINX Unit → nxt_php_request_handler()
↓
创建协程 (zend_async_coroutine_create)
↓
nxt_php_request_coroutine_entry()
↓
创建 Request/Response 对象
↓
调用 entrypoint.php 中的回调函数
↓
response->write() → nxt_unit_response_write_nb()
↓
response->end() → nxt_unit_request_done()
非阻塞 I/O
调用 response-\>write(data) 时：
数据通过 nxt_unit_response_write_nb() 发送
缓冲区满了，剩余数据进 drain_queue
缓冲区空出来，触发 shm_ack_handler
异步写入，不阻塞协程
配置
unit-config.json
{
"applications": {
"my-php-async-app": {
"type": "php",
"async": true, // 启用 TrueAsync 模式
"processes": 2, // 工作器数量
"entrypoint": "/path/to/entrypoint.php",
"working_directory": "/path/to/",
"root": "/path/to/"
}
},
"listeners": {
"127.0.0.1:8080": {
"pass": "applications/my-php-async-app"
}
}
}
重要："async": true 会激活 TrueAsync SAPI，而不是标准的 PHP SAPI。
加载配置
curl -X PUT --data-binary @unit-config.json \
--unix-socket /tmp/unit/control.unit.sock \
entrypoint.php
基本结构：
use NginxUnit\HttpServer;
use NginxUnit\Request;
use NginxUnit\Response;
set_time_limit(0);
// 注册请求处理器
HttpServer::onRequest(static function (Request request, Response response) {
// 拿请求数据
method = request->getMethod();
uri = request->getUri();
// 设响应头
$response->setHeader('Content-Type', 'application/json');
$response->setStatus(200);
// 发数据（非阻塞）
$response->write(json_encode([
'message' => 'Hello from TrueAsync!',
'method' => $method,
'uri' => $uri
]));
// 结束响应
$response->end();
});
API 参考
Request
getMethod(): string - HTTP 方法（GET、POST 等）
getUri(): string - 请求 URI
getRequestContext(): ?mixed - 请求上下文（TODO）
getRequestContextParameters(): ?mixed - 上下文参数（TODO）
createResponse(): Response - 创建 Response 对象（通常不需要）
Response
setStatus(int $code): bool - 设置 HTTP 状态码
setHeader(string name, string value): bool - 添加响应头
write(string $data): bool - 发送数据（非阻塞操作）
end(): bool - 完成响应并释放资源
注意：
setStatus() 和 setHeader() 要在第一次 write() 之前调用
调用过 write() 后，响应头就发出去了
end() 必须调用，完成请求
生命周期
HttpServer::onRequest(function (Request req, Response resp) {
// 1. 响应头还能改
$resp->setStatus(200);
$resp->setHeader('Content-Type', 'text/plain');
// 2. 第一次 write() 把响应头发出去了
$resp->write('Hello ');
// 3. 现在响应头改不了了
// $resp->setHeader() → 报错！
// 4. 可以继续写数据
$resp->write('World!');
// 5. 结束请求（必须调！）
$resp->end();
});
运行和测试
启动 NGINX Unit
./build/sbin/unitd \
--no-daemon \
--log /tmp/unit/unit.log \
--state /tmp/unit \
--control unix:/tmp/unit/control.unit.sock \
--pid /tmp/unit/unit.pid \
--modules ./build/lib/unit/modules
重要：--modules 参数必须加，用来加载 PHP 模块。
查看日志
tail -f /tmp/unit/unit.log
测试
响应：
{
"message": "Hello from NginxUnit TrueAsync HttpServer!",
"method": "GET",
"uri": "/",
"timestamp": "2025-10-04 15:30:00"
}
负载测试
wrk -t4 -c100 -d30s http://127.0.0.1:8080/
调试
GDB
gdb ./build/sbin/unitd
(gdb) set follow-fork-mode child
(gdb) run --no-daemon --log /tmp/unit/unit.log ...
设置断点
break nxt_php_request_handler
break nxt_php_request_coroutine_entry
break nxt_unit_response_write_nb
实用命令
停止所有 NGINX Unit 进程
pkill -9 unitd
检查控制套接字
ls -la /tmp/unit/control.unit.sock
获取当前配置
curl --unix-socket /tmp/unit/control.unit.sock http://localhost/config
内部实现
初始化
nxt_php_extension_init() 在 NginxUnit 命名空间注册类
worker 启动时加载 entrypoint.php
HttpServer::onRequest() 把回调存到 nxt_php_request_callback
请求处理
NGINX Unit 调用 nxt_php_request_handler(req)
创建协程：zend_async_coroutine_create(nxt_php_request_coroutine_entry)
协程指针存到 req
协程加入激活队列
控制权回到事件循环 nxt_unit_run()
协程激活
事件循环调用 nxt_unit_response_buf_alloc 回调
回调通过 zend_async_coroutine_activate() 激活协程
执行 nxt_php_request_coroutine_entry()
创建 PHP Request/Response 对象
调用用户回调
response->end() 后协程结束
异步发送
response->write() → nxt_unit_response_write_nb()
没发完，剩下的进 drain_queue
缓冲区空了，触发 shm_ack_handler()
shm_ack_handler 继续写，需要的话调 end()
未来计划
实现 Request::getRequestContext()
添加请求头支持
添加 POST 数据解析
WebSocket 支持
流式响应
总结
NGINX Unit TrueAsync PHP 集成让 PHP 真正拥有了异步处理能力。通过协程机制，单个进程可以同时处理多个请求，这在过去是无法想象的。
对于 PHP 生态来说，这是一个重要的转折点。传统的 PHP-FPM 模式下，每个请求独占一个进程，在高并发场景下资源消耗巨大。现在有了 TrueAsync，PHP 可以像 Node.js、Go 那样高效处理并发请求，同时保持语言本身的简洁性。
虽然目前还有一些功能在开发中，比如完整的请求头支持、POST 数据解析、WebSocket 等，但现有的功能已经足够构建高性能的 API 服务。非阻塞 I/O、协程调度、事件循环------这些核心机制都已经就位。
对于需要处理高并发请求的 PHP 应用，特别是 API 服务、微服务架构，NGINX Unit TrueAsync 提供了一个值得认真考虑的选择。它不需要改变太多现有代码结构，却能带来性能上的显著提升。