reactphp-x/gateway-worker

Distributed long-connection gateway for reactphp-x/worker (TCP + WebSocket)

dev-master 2026-07-13 11:03 UTC

Requires

• php: >=8.1
• react/async: ^4.0
• react/event-loop: ^1.6
• react/http: ^1.11
• react/promise: ^3.0
• react/socket: ^1.16
• react/stream: ^1.4
• reactphp-x/websocket-middleware: ^1.0
• reactphp-x/worker: dev-master

MIT

Published on Packagist.org on 2026-07-13 11:04 UTC

README

基于 reactphp-x/worker 的分布式长连接 GatewayWorker 实现，架构参考 Workerman GatewayWorker，支持 TCP 与 WebSocket（WebSocket 使用 reactphp-x/websocket-middleware）。

架构

Client (TCP/WebSocket)
        ↓
    Gateway  ←→  Register  ←→  BusinessWorker
        ↓                            ↓
   转发连接事件                  Events 业务逻辑

• Register：服务注册中心，协调 Gateway 与 BusinessWorker 地址发现
• Gateway：接受客户端长连接，通过二进制 GatewayProtocol 转发给 BusinessWorker
• BusinessWorker：处理 onConnect / onMessage / onClose 业务逻辑

安装

composer install

运行示例

cd examples
php start.php start

默认端口：

服务	地址
Register	127.0.0.1:1238（仅内网）
Gateway TCP	0.0.0.0:8282
Gateway WebSocket	ws://0.0.0.0:8283/ws
BusinessWorker	4 进程

TCP 测试

telnet 127.0.0.1 8282

WebSocket 测试

<script>
  var conn = new WebSocket('ws://127.0.0.1:8283/ws');
  conn.onopen = () => conn.send('Hello!');
  conn.onmessage = (e) => console.log(e.data);
</script>

WebSocket 二进制帧

BusinessWorker 发送非 JSON 载荷（如 Needle Engine SyncedTransform 的 FlatBuffer STRS 消息）时，须将 $raw 设为 true：

// 单播二进制
Gateway::sendToClient($clientId, $binaryPayload, raw: true);

// 组播二进制（第四个参数）
Gateway::sendToGroup($group, $binaryPayload, $excludeClientId, raw: true);

Gateway 收到 FLAG_NOT_CALL_ENCODE 后，会以 WebSocket binary frame（opcode 0x2）发给浏览器，而不是 text frame。若以 text frame 发送非 UTF-8 数据，浏览器会报错并断开连接。

自定义应用

参考 examples/Applications/YourApp/：

• start_register.php — 注册中心
• start_gateway_tcp.php — TCP Gateway
• start_gateway_websocket.php — WebSocket Gateway
• start_businessworker.php — 业务 Worker
• Events.php — 业务回调

License

MIT