All documentation

事件触发任务 AI 编程指南 ZH

面向 AI 编程工具的 PHPTS 「事件触发任务」PHP 脚本编写与「Server → Client 主动推送」规范:五类事件脚本模板、PHPTS_EVENT_* 元数据、输出与关闭约定、共用推送接口及完整调用示例。教 AI 编程工具如何去写对应的 PHP 代码,并让用户了解整个「事件触发任务」的生命周期流程。

Markdown 原文下载: event-ai-guide-zh.md(可直接交给 AI 编程工具阅读)

读者:AI 编程工具(Trae / Claude Code / Cursor / Codex / opencode 等)。
目标:让 AI 在看不到 PHPTS 源码、甚至不在 PHPTS 服务器上的情况下,也能正确编写「事件触发任务」的 PHP 脚本,并实现 Server → Client 主动推送。
适用版本:PHPTS 2.0.13.1(2026-11-20)。更早版本请先看文末「版本与特性时间线」。
本文只描述对外契约(脚本入参、输出语义、推送接口),不依赖本仓库路径与内部实现。

0. 先读这一节:使用本文档的正确姿势

0.1 三条硬事实

  1. PHP 不持有长连接。WebSocket / TCP / MQTT / 串口的长连接全部由 Rust 网关 phpts-event.exe 持有;PHP 只是一次事件一次执行的无状态逻辑单元。
  2. 事件脚本的「输出」就是业务数据,不是网页、不是 HTTP 响应。echo 什么,网关就把什么回给客户端(WebSocket 文本帧 / TCP 原始字节 / MQTT 消息 / 串口字节)。
  3. 主动推送不是 PHP 直接写 socket,而是调用网关的共用 HTTP 推送接口(默认 http://127.0.0.1:3379),由网关投递给在线连接。

0.2 本文档可能不在 PHPTS 服务器上被读取

因此:

  • 文中所有路径、端口、Token 都是占位符,必须向用户确认或在目标环境读取,禁止猜测。
  • 不要假设 PHPTS 安装在某个固定盘符;脚本路径以PHPTS 安装目录(base)为基准的相对路径配置,代码内部用 __DIR__ 定位同目录文件。
  • 如果 AI 无法访问 PHPTS 安装目录,就只输出脚本内容 + 配置项 + 自检命令,并在交付说明里列出「需要人工在界面确认的项」。
  • 运行在另一台服务器上的 PHP 代码,只能走网络调用推送接口;phpts_kv_* 扩展在那台机器上不可用(见 §6.7)。

0.3 环境探测命令(Windows PowerShell / curl)

# 任务池是否在监听(事件脚本实际由它执行)
Test-NetConnection 127.0.0.1 -Port 6285

# 推送接口是否可达(未设 Token 时直接返回客户端列表)
curl.exe -s "http://127.0.0.1:3379/ws/clients"
curl.exe -s "http://127.0.0.1:3379/tcp/clients"
curl.exe -s "http://127.0.0.1:3379/serial/ports"
# 确认 PHP 8.5 任务池加载了 phpts_kv(php.ini 在 data\conf\php8.5-task\php.ini)
Select-String -Path "data\conf\php8.5-task\php.ini" -Pattern "extension=phpts_kv"

0.4 配置从哪来

推送接口地址/端口/Token:「事件触发任务」页 →「全局委托配置与推送服务」Tab →「(Server → Client)主动推送接口」卡;落盘在 data\conf\phpts-event\event.conf 的 [pushapi]

WebSocket 端口:「WebSocket 服务器」Tab(默认 3380,TLS 3343)

TCP 监听端口:「TCP 服务器」Tab 的端口规则(默认从 59301 起)

事件脚本:规则表里的「PHP 脚本」;相对路径以 PHPTS 安装目录为基准

超时:全局 [server] fcgi_timeout(默认 300 秒)+ 单规则 timeout(0 = 继承)

没有拿到 Token 时,不要把 Token 写成空字符串后当作“无需鉴权”。先问用户;用户确认未配置 Token 才可以留空。

1. 运行模型(必须先理解)

  设备 / 浏览器 / MQTT 客户端 / 串口设备
              │  长连接(WS / TCP / MQTT / COM)
              ▼
     ┌──────────────────────────────┐
     │      phpts-event.exe         │   长连接、分帧、心跳、路由、注册表
     │  WebSocket / TCP / MQTT /    │
     │  串口 / 定时器 / 推送接口     │
     └──────────────┬───────────────┘
                    │ 每个事件一次 FastCGI 委托(127.0.0.1:6285)
                    ▼
     ┌──────────────────────────────┐
     │  PHP FastCGI (任务) 进程池    │   phpts-php-task.exe × N
     │  执行你的 PHP 脚本            │   无状态、可并发复用
     └──────────────┬───────────────┘
                    │ 脚本输出
                    ▼
        原路回写:WS 文本帧 / TCP 字节 /
        MQTT 应答主题 / 串口字节 / 日志

  任意普通 PHP(Nginx Web、CLI、定时脚本)
              │ HTTP POST
              ▼
     http://127.0.0.1:3379/ws/send
     http://127.0.0.1:3379/tcp/send
     http://127.0.0.1:3379/serial/send
              │
              ▼
      phpts-event.exe 按 client_id / 串口名投递给在线连接


1.1 必须记住的 8 条行为

一次事件一次请求 :每次消息/帧/定时触发都会重新执行整个 PHP 文件;不要依赖进程内全局变量跨事件保存状态

无 Session、无 Cookie、无 HTTP 头 :不要用 $_SESSION、$_COOKIE、getallheaders()、$_FILES

请求方法是 POST :正文用 file_get_contents('php://input') 读取;只有定时器的「附加参数」能通过 $_GET 拿到

单连接串行委托 :同一条 WS/TCP 连接,上一条在途时不会读下一条;脚本慢会直接降低该连接吞吐

超时双层 :全局默认 300 秒,单规则可覆盖;超时后网关丢弃本次结果(WS 不回帧但不断连,TCP 不写回但不断连)

不自动拉起任务池 :任务池没启动时,委托直接失败;先启动「PHP FastCGI (任务)」

输出即协议数据 :任何 PHP 警告、var_dump、BOM 都会混进业务数据,可能直接破坏客户端协议

脚本路径相对 base :规则里填 wwwroot/event/ws.php 等价于 <PHPTS安装目录>/wwwroot/event/ws.php;绝对路径也可

1.2 脚本运行环境

  • PHP 8.5(任务池当前只支持 8.5)。
  • 独立的任务池 php.ini:data\conf\php8.5-task\php.ini。
  • phpts_kv 默认已开启;用 function_exists('phpts_kv_set') 做能力探测。
  • 任务池 php.ini 种子的 display_errors = On 。这是最容易踩的坑:一条 Warning 就会混进 WS 帧/TCP 字节里。每个脚本开头必须关掉(不要依赖服务器配置):
ini_set('display_errors', '0');
error_reporting(E_ALL);
  • 没有设置 date.timezone 时 PHP 默认按 UTC。需要本地时间就显式设置:
date_default_timezone_set('Asia/Shanghai');
  • 工作目录不保证;所有文件操作都用 __DIR__ 拼接,不要依赖 getcwd()。
  • DOCUMENT_ROOT 恒为 <base>/data/wwwroot,与脚本真实位置无关,不要用它拼脚本路径。

2. 事件脚本通用模板

所有事件脚本都建议从下面这个骨架开始:

<?php
// 1) 输出就是协议数据:关闭 PHP 错误直出,错误走日志
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');

// 2) 原始输入(二进制安全),不要用 $_POST
$raw = file_get_contents('php://input');

// 3) 网关注入的元数据
$type     = $_SERVER['PHPTS_EVENT_TYPE']     ?? '';  // websocket|tcp|mqtt|serial|timer
$name     = $_SERVER['PHPTS_EVENT_NAME']     ?? '';  // 规则名
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';  // WS/TCP 连接 ID;MQTT 为订阅 Client ID;串口/定时器为空
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';  // WS/TCP 对端 IP(不含端口);其余为空
$timeout  = (int)($_SERVER['PHPTS_EVENT_TIMEOUT'] ?? 300); // 本次生效超时(秒)

// 4) 业务处理:任何异常都自己兜住,返回可识别的错误数据
try {
    $result = ['ok' => true, 'echo' => $raw];
    echo json_encode($result, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
} catch (Throwable $e) {
    error_log('[event] ' . $e->getMessage());
    echo json_encode(['ok' => false, 'error' => 'internal error'], JSON_UNESCAPED_UNICODE);
}

2.1 元数据变量对照表

PHPTS_EVENT_TYPE
WebSocket:websocket
TCP:tcp
MQTT:mqtt
串口:serial
定时器:timer

PHPTS_EVENT_NAME
WebSocket:规则名
TCP:规则名
MQTT:规则名
串口:规则名
定时器:规则名

PHPTS_EVENT_PATH
WebSocket:命中的握手路径
TCP:空
MQTT:空
串口:空
定时器:空

PHPTS_EVENT_PORT
WebSocket:空
TCP:监听端口
MQTT:空
串口:串口名(如 COM3)
定时器:空

PHPTS_EVENT_TOPIC
WebSocket:空
TCP:空
MQTT:实际命中主题
串口:空
定时器:空

PHPTS_EVENT_CLIENTID
WebSocket:连接 ID
TCP:连接 ID
MQTT:订阅 Client ID
串口:空
定时器:空

PHPTS_EVENT_CLIENTIP
WebSocket:客户端 IP
TCP:客户端 IP
MQTT:空
串口:空
定时器:空

PHPTS_EVENT_TIMEOUT
WebSocket:本次超时秒数
TCP:同左
MQTT:同左
串口:同左
定时器:同左

2.2 输出约定

WebSocket:作为 text 帧回送同一条连接;输出为空也会回一个空文本帧

TCP:原始字节原样写回同一条连接;输出为空则不写回

MQTT:输出发布到规则的「应答主题」;未配置应答主题或输出为空则不发布

串口:仅当规则开启「应答写回串口」时,输出原样写回串口

定时器:输出只写入网关日志 logs/phpts-event-YYYY-MM-DD.log

补充:脚本里的 header() 调用没有意义(FastCGI 的 CGI 头块会被网关剥掉),不要用它设置 Content-Type;直接输出正文即可。

2.3 主动关闭连接(仅 WS / TCP)

脚本输出恰好等于 __PHPTS_CLOSE__(首尾 ASCII 空白不计)时:

  • WebSocket:网关回 close 1000 并关闭连接,该文本不发送;
  • TCP:网关直接断开连接,不写回任何字节。
if (trim($raw) === 'QUIT') {
    echo '__PHPTS_CLOSE__';
    return;
}

以下都不算约定值,会当普通业务输出处理:

echo '"__PHPTS_CLOSE__"';             // 带引号
echo json_encode(['t' => '__PHPTS_CLOSE__']); // JSON 包装
echo "__PHPTS_CLOSE__\nextra";        // 拼接了其它内容

2.4 日志与调试

  • 用 error_log() 或写文件,不要 echo/var_dump 调试。
  • 写文件用 __DIR__ 定位,并加 LOCK_EX 防止并发写坏:
file_put_contents(__DIR__ . '/event.log', date('c') . ' ' . $line . PHP_EOL, FILE_APPEND | LOCK_EX);
  • 网关日志:logs/phpts-event-<本地日期>.log;PHP 的 stderr 也会进这里。
  • 修改脚本不需要重启网关或任务池,下一次事件即生效。

3. 五类事件脚本

3.1 WebSocket 服务器

绑定关系:客户端握手 URL 的 path 与规则「路径」精确匹配(查询串不参与匹配)。路径不匹配返回 404 并关闭连接。

输入:一条完整的 WebSocket 消息(text 或 binary 的载荷原始字节);单条消息上限 1MB,超限网关回 close 1009。

输出:一条 text 帧。注意:即使客户端发的是 binary,网关回包也固定是 text 帧;二进制业务请在 PHP 里做 base64/hex 编码后再输出。

客户端身份:握手可带 ?client_id=<id>(也接受 ?id=),白名单 [A-Za-z0-9_.:-]{1,64};不带则网关自动分配 ws-xxxxxxxx。同 ID 新连接会顶掉旧连接(旧连接收到 close 1000)。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);

$raw = file_get_contents('php://input');
$name     = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$path     = $_SERVER['PHPTS_EVENT_PATH'] ?? '';
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';

if (trim($raw) === 'QUIT') {
    echo '__PHPTS_CLOSE__';
    return;
}

$data = json_decode($raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    $data = $raw; // 不是 JSON 就保留原文
}

echo json_encode([
    'ok'     => true,
    'type'   => 'ack',
    'rule'   => $name,
    'path'   => $path,
    'client' => $clientid,
    'ip'     => $clientip,
    'recv'   => $data,
    'time'   => date('c'),
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

要点:

  • 网关负责协议层 Ping/Pong 与心跳;业务脚本无需处理 ping 帧。
  • 浏览器原生 WebSocket 会自动回 Pong;自研客户端必须实现 Pong,否则一个心跳周期后会被 close 1001。
  • 业务协议建议统一 JSON 信封,见 §6.8。

3.2 TCP 服务器

绑定关系:每个 [tcp.<规则名>] 是一个独立监听端口,绑定各自的脚本。所有端口共用 [tcpserver] listen 地址。

分帧(关键):

idle(缺省)
行为:连续静默满 idle_ms(缺省 50ms)后,把缓冲合并成一帧
适用:一次写入一帧、无分隔符的透传设备

line
行为:按分隔符切帧,载荷不含分隔符
适用:行协议(\r\n 结尾的 JSON、AT 指令等)

none
行为:每次读到的 TCP 数据段直接成一帧
适用:协议自带长度字段,脚本自己切帧

输入:一帧原始字节。

输出:原样写回同一条 TCP 连接;输出为空不写回。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);

$frame    = file_get_contents('php://input');
$port     = $_SERVER['PHPTS_EVENT_PORT'] ?? '';
$name     = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';

// 文本协议才 trim;二进制协议(Modbus RTU 等)绝不能 trim
$cmd = trim($frame);

if ($cmd === 'QUIT') {
    echo '__PHPTS_CLOSE__';
    return;
}
if ($cmd === 'PING') {
    echo "PONG\r\n";
} elseif ($cmd !== '') {
    echo "OK\r\n";
}

file_put_contents(
    __DIR__ . '/tcp.log',
    date('c') . " {$clientip} {$port} {$cmd}" . PHP_EOL,
    FILE_APPEND | LOCK_EX
);

要点:

  • line 模式已经剥掉分隔符;如果客户端协议要求回包也带分隔符,脚本自己补。
  • 二进制回包直接 echo 原始字节,例如 echo "\xAA\x55\x01\x00";,不要经过 JSON。
  • 空输出是合法的(例如只做入库、不需要应答),客户端要能接受无回包。
  • 单连接串行:脚本执行期间的后续字节会排队,慢脚本会让 idle 的帧边界变粗。

3.3 MQTT 订阅

绑定关系:消息主题与规则「订阅主题」按 MQTT 通配符匹配(+ 一层、# 多层)。

输入:消息体原始字节。QoS 1 的 PUBACK 由网关自动回,脚本不用管。

输出:发布到规则的「应答主题」;应答主题同样支持 +/#,按实际命中主题展开。未配置应答主题或输出为空则不发布。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);

$payload = file_get_contents('php://input');
$topic   = $_SERVER['PHPTS_EVENT_TOPIC'] ?? '';
$name    = $_SERVER['PHPTS_EVENT_NAME'] ?? '';
$client  = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? ''; // 订阅用的 Client ID,不是每台设备

$data = json_decode($payload, true);
if (!is_array($data)) {
    $data = ['raw' => $payload];
}

// 业务处理:入库、报警、联动等
file_put_contents(
    __DIR__ . '/sensor.log',
    date('c') . " {$topic} {$payload}" . PHP_EOL,
    FILE_APPEND | LOCK_EX
);

// 有应答主题时,这段输出会被发布出去
echo json_encode([
    'ok'    => true,
    'rule'  => $name,
    'topic' => $topic,
    'data'  => $data,
], JSON_UNESCAPED_UNICODE);

要点:

  • PHPTS_EVENT_CLIENTID 是订阅客户端自己的 ID,所有消息都一样,不能拿它区分设备;设备身份应从 payload 或主题层级里取。
  • MQTT 没有「客户端断开」联动,phpts_kv 登记要么设 TTL,要么业务主动清理。

3.4 串口监听

绑定关系:每个 [serial.<规则名>] 独立占用一个 COM 口,独立线路参数(波特率/数据位/停止位/校验位)与脚本。

分帧:与 TCP 同名但有一处关键差异:

  • idle:静默窗口冲刷,缺省 50ms;
  • none:每次读到即成一帧;
  • line:按分隔符切帧,帧内包含分隔符本身(与 TCP 剥分隔符不同),脚本需要自己 rtrim。

输入:一帧原始字节。

输出:仅当规则「应答写回串口」开启时,输出原样写回串口。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);

$frame = file_get_contents('php://input');
$port  = $_SERVER['PHPTS_EVENT_PORT'] ?? '';
$name  = $_SERVER['PHPTS_EVENT_NAME'] ?? '';

// line 模式帧内含分隔符;文本协议这里剥掉。二进制协议不要 rtrim
$cmd = rtrim($frame, "\r\n");

if ($cmd === 'PING') {
    echo "PONG\r\n";
} elseif ($cmd !== '') {
    echo "OK\r\n";
}

要点:

  • 不要在脚本里用 phpts_serial_open() 再打开同一个 COM 口:网关已独占打开(共享位 0),必然失败。
  • 半双工 485 设备靠 echo=1 把应答写回同一条线。
  • 需要主动写串口(不是应答)时,走推送接口 /serial/send,见 §6。
  • Modbus RTU 是二进制协议:绝不能用 line (数据区和 CRC 可能含 0x0A/0x0D);用 idle 配小窗口(9600 波特约 10ms),或让脚本按功能码自己切帧。

3.5 定时器

触发方式(每条规则独立):

interval(缺省)
字段:every
说明:间隔秒(1-86400),防漂移

daily
字段:at
说明:每天本地时刻 HH:MM

weekly
字段:at + weekdays
说明:1=周一 … 7=周日,留空=全周

monthly
字段:at + days
说明:每月几号(1-31),留空=全选

输入:请求体为空;规则的「附加参数」作为 QUERY_STRING,脚本用 $_GET 读取。

输出:只写入网关日志,不返回任何客户端。

防重入(no_reentry,缺省开):上一轮未返回时跳过本轮。关闭后同一脚本可能并发多份,必须自己保证幂等。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');

$job  = $_GET['job'] ?? 'daily';
$keep = (int)($_GET['keep'] ?? 7);

// 示例:清理本目录 tmp 下过期文件
$dir = __DIR__ . '/tmp';
foreach (glob($dir . '/*') ?: [] as $file) {
    if (is_file($file) && filemtime($file) < time() - $keep * 86400) {
        @unlink($file);
    }
}

// 输出只进网关日志
echo "job={$job} keep={$keep}" . PHP_EOL;

要点:

  • 定时器最适合做「服务端主动推送」的定时任务,例如每天 08:30 给登记过的用户推送提醒(见 §7.4)。
  • 单轮执行时间不要超过触发周期;如果会超,保持 no_reentry=1,或把脚本改成投递任务后立即返回。

4. 事件脚本的硬性禁止清单

用 $_POST / $_GET 读事件正文:事件走 FastCGI,正文在 php://input;$_GET 只有定时器附加参数

echo / print_r / var_dump 调试:输出就是协议数据,会破坏 WS/TCP/串口报文

文件开头有 BOM、?> 后有空白:BOM 会进入首帧;还会让 __PHPTS_CLOSE__ 精确匹配失败

依赖 $_SESSION / $_COOKIE / 请求头:事件不是 HTTP 请求,没有这些

依赖全局变量跨请求保存状态:每个事件都是新的请求上下文

依赖 getcwd() :工作目录不保证,统一用 __DIR__

在 WS 文本帧里发非 UTF-8 二进制:文本帧要求 UTF-8;二进制请 base64/hex 后传输

认为 echo 空字符串 = 关闭连接:WS 空输出会发空帧;关闭连接必须输出 __PHPTS_CLOSE__

在串口脚本里重复打开同一 COM 口:网关已独占,必然失败

用 line 分帧处理 Modbus RTU:二进制里会出现假分隔符,帧随机错位

在事件脚本里 new WebSocket() / fsockopen 连客户端:PHP 不持有长连接;主动推送只能走推送接口

硬编码 Token / 端口 / 路径:不同安装必然不同;必须向用户确认或读配置

假设推送返回 ok 等于客户端已收到:接口只保证「已入队」,没有端到端 ACK

5. 主动推送:先分清两件事

应答式(脚本 echo)
是谁在发:当前事件脚本
能发给谁:只能回当前这条连接
适用:请求-响应、ACK

主动推送(HTTP 接口)
是谁在发:任意 PHP(Web 页、定时脚本、CLI、甚至另一个事件脚本)
能发给谁:任意在线 WS 客户端 / TCP 连接 / 已打开串口
适用:通知、告警、指令下发、广播

需要「服务端在任意时刻主动找客户端」时,一律用主动推送,不要试图让事件脚本长时间挂着。

6. 共用推送接口(Server → Client)

6.1 基本参数

监听地址
默认值:127.0.0.1
说明:只允许本机;跨机推送需改为 0.0.0.0 或 [::]

端口
默认值:3379
说明:不能与 WS/TCP 端口重复

鉴权
默认值:[pushapi] token
说明:非空时,请求必须带 ?token= 或请求头 X-PHPTS-Token

请求体上限
默认值:1MB
说明:Content-Length 超过返回 413

请求头上限
默认值:64KB
说明:超过返回 431

连接超时
默认值:服务端 3 秒读写
说明:客户端也应设短超时(建议 3 秒)

名称大小写
默认值:端点与参数名区分大小写
说明:路径写 /ws/send,不要写成 /WS/send

URI 前缀决定投递目标:/ws/ → WebSocket 文本帧;/tcp/ → TCP 原始字节;/serial/ → 串口原始字节。

推送接口与子服务生命周期解耦:WebSocket / TCP / 串口子服务停止时,对应注册表清空,该前缀端点回 404(client not found / port not found),其它前缀不受影响;推送接口本身也可在界面「(Server → Client)主动推送接口」卡上独立启动/停止/重启。

6.2 端点总表

WebSocket

GET
路径:/ws/clients[?limit=N]
说明:在线客户端列表:{"ok":true,"clients":["a","b"],"total":N},最新连接在前

POST
路径:/ws/send?client=<id[,id...]>[&key=<kv键[,键...]>]
说明:请求体作为 text 帧发送;单目标命中回 {"ok":true},多目标回 sent/missing

GET
路径:/ws/send?client=<id>&text=<数据>
说明:便捷 GET;有请求体时请求体优先

POST
路径:/ws/broadcast
说明:请求体发给全部在线客户端,回 {"ok":true,"sent":N}

TCP

GET
路径:/tcp/clients[?limit=N]
说明:在线连接:{"ok":true,"clients":[{"id":"tcp-...","port":59301}],"total":N}

POST
路径:/tcp/send?client=<id[,id...]>[&key=<kv键>]
说明:请求体原始字节写入目标连接

GET
路径:/tcp/send?client=<id>&data=<内容>
说明:便捷 GET

POST/GET
路径:/tcp/broadcast[?port=N]
说明:发给全部连接;带 port 只发该监听端口

串口

GET
路径:/serial/ports
说明:已打开串口:{"ok":true,"ports":["COM3"]}

POST
路径:/serial/send?port=COM3[,COM4]
说明:请求体原始字节写入指定串口

GET
路径:/serial/send?port=COM3&data=<内容>
说明:便捷 GET

POST/GET
路径:/serial/broadcast
说明:写入全部已打开串口,回 {"ok":true,"sent":N}

6.2.1 参数与边界(按网关实现核对)

正文来源:有请求体时用请求体;请求体为空时取查询串 text=,再退到 data=(三个前缀都接受这两种便捷参数)

空正文:send 与 broadcast 一律返回 400 {"ok":false,"error":"empty payload"};GET 便捷形式必须带 text= 或 data=

目标参数别名:client= 也接受 client_id=;串口 port= 也接受 client=

多目标:client= / key= / port= 均支持逗号分隔,网关去空白、去重、保序

单目标响应:只给一个 client= 且未给 key= 时,命中回 {"ok":true}(兼容旧调用方)

多目标响应:{"ok":true,"sent":N,"missing":[...]};missing 项带 client: / kv: / port: 前缀

全部未命中:404,body 带 "sent":0 与 missing;phpts_kv 整体不可用时额外带 "kv":"unavailable"

广播:回 {"ok":true,"sent":N};一个目标都没有时 sent:0 仍是 200,不算错误

Token 优先级:配置了 Token 时先看查询串 token=,没有再取请求头 X-PHPTS-Token

send 端点没有“空消息”语义:空正文直接 400。确实要给客户端发空文本帧时,发一个空格或业务心跳字段(如 {"type":"ping"}),不要留空。

6.3 身份与目标

WebSocket
目标 ID:客户端 ID
怎么来:握手 ?client_id= 自报,或网关自动分配
是否自动前缀:自报存原值;自动为 ws-xxxxxxxx

TCP
目标 ID:连接 ID
怎么来:网关自动分配
是否自动前缀:tcp-xxxxxxxx

MQTT
目标 ID:订阅 Client ID
怎么来:配置里自命名
是否自动前缀:无前缀

串口
目标 ID:串口名
怎么来:规则里的 COMx
是否自动前缀:无

  • client= 支持逗号分隔多个 ID,也接受别名 client_id=;
  • key= 支持逗号分隔多个 phpts_kv 键,网关按键读出登记的客户端 ID 再投递;
  • client= 与 key= 可以同时给,取并集;
  • 串口不支持 key=,只认 port=。

6.4 响应口径

200
body:{"ok":true}
含义:单目标命中并入队(旧格式)

200
body:{"ok":true,"sent":N,"missing":[...]}
含义:多目标/key= 形式;missing 项带 client: / kv: / port: 前缀

200
body:{"ok":true,"sent":N}
含义:广播

400
body:{"ok":false,"error":"missing client"}
含义:没给 client= 也没给 key=

400
body:{"ok":false,"error":"missing port"}
含义:串口没给 port=

400
body:{"ok":false,"error":"empty payload"}
含义:send / 广播正文为空(GET 便捷形式未带 text=/data=)

403
body:{"ok":false,"error":"invalid token"}
含义:Token 不匹配

404
body:{"ok":false,"error":"client not found","sent":0,"missing":[...]}
含义:目标全部未命中(离线 / ID 不存在 / 子服务已停)

404
body:{"ok":false,"error":"port not found","sent":0,"missing":[...]}
含义:串口全部未打开

404
body:{"ok":false,"error":"unknown endpoint"}
含义:路径或前缀不对

405
body:{"ok":false,"error":"method not allowed"}
含义:端点存在但方法不对

413
body:{"ok":false,"error":"body too large"}
含义:Content-Length 超过 1MB

431
body:{"ok":false,"error":"header too large"}
含义:请求头超过 64KB

200 ok 只代表已投进连接的发送队列,不代表客户端业务层已处理。需要可靠送达时,业务协议自己做 ACK/重试。

6.5 推荐封装:phpts_push()

把下面这段放进一个公共文件(例如 wwwroot/event/push.php),其他脚本 require_once __DIR__ . '/push.php';。

<?php
/**
 * 调用 PHPTS 共用推送接口。
 *
 * @param string $channel ws|tcp|serial
 * @param string $payload 原始字节(WS 按 UTF-8 文本帧发送)
 * @param array  $opts    client/key/port/broadcast/port_filter/base/token/timeout
 * @return array{ok:bool,status:int,body:string,json:?array}
 */
function phpts_push(string $channel, string $payload, array $opts = []): array
{
    $base    = rtrim((string)($opts['base'] ?? (getenv('PHPTS_PUSH_BASE') ?: 'http://127.0.0.1:3379')), '/');
    $token   = (string)($opts['token'] ?? (getenv('PHPTS_PUSH_TOKEN') ?: ''));
    $timeout = (int)($opts['timeout'] ?? 3);

    $broadcast = !empty($opts['broadcast']);
    $path      = '/' . $channel . ($broadcast ? '/broadcast' : '/send');

    $query = [];
    foreach (['client', 'key', 'port'] as $k) {
        if (!empty($opts[$k])) {
            $query[$k] = implode(',', (array)$opts[$k]);
        }
    }
    if (!empty($opts['port_filter'])) {
        $query['port'] = (string)$opts['port_filter'];
    }
    $url = $base . $path . ($query ? '?' . http_build_query($query) : '');

    $headers = ['Content-Type: application/octet-stream'];
    if ($token !== '') {
        $headers[] = 'X-PHPTS-Token: ' . $token;
    }

    $status = 0;
    $body   = '';

    if (function_exists('curl_init')) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => $payload,
            CURLOPT_HTTPHEADER     => $headers,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => $timeout,
            CURLOPT_CONNECTTIMEOUT => min(2, $timeout),
        ]);
        $res    = curl_exec($ch);
        $status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $body   = is_string($res) ? $res : '';
    } else {
        $ctx = stream_context_create(['http' => [
            'method'        => 'POST',
            'header'        => implode("\r\n", $headers) . "\r\n",
            'content'       => $payload,
            'timeout'       => $timeout,
            'ignore_errors' => true,
        ]]);
        $res    = @file_get_contents($url, false, $ctx);
        $body   = is_string($res) ? $res : '';
        foreach ($http_response_header ?? [] as $line) {
            if (preg_match('#^HTTP/\S+\s+(\d{3})#', $line, $m)) {
                $status = (int)$m[1];
            }
        }
    }

    $json = json_decode($body, true);

    return [
        'ok'     => $status >= 200 && $status < 300,
        'status' => $status,
        'body'   => $body,
        'json'   => is_array($json) ? $json : null,
    ];
}

说明:

  • 优先用 cURL,未启用时退回 allow_url_fopen 流封装(PHPTS 任务池默认 allow_url_fopen = On)。
  • Token 放在请求头,避免出现在 URL 与访问日志里。
  • status = 0 表示连不上:推送接口没启动、地址/端口错、被防火墙拦截。
  • 多目标与 key= 用逗号分隔;http_build_query 会百分号编码,网关会自动解码。
  • 键名里不要带空格(http_build_query 会把空格编成 +,网关按字面解析)。业务键建议只用 字母 数字 : _ - .。

6.6 客户端 ID 登记:phpts_kv

WebSocket/TCP 连接建立后,脚本可以把「业务身份 → 连接 ID」登记到进程间共享内存,之后任意 PHP 都能凭业务身份找到连接。

phpts_kv_set(string $key, string $value, int $ttl_seconds = 0): bool :写入/覆盖;ttl=0 永不过期

phpts_kv_get(string $key): ?string :读取;不存在/过期返回 null

phpts_kv_del(string $key): bool :按键删除

phpts_kv_del_by_value(string $value): array :按值删除全部命中,返回被删键列表

phpts_kv_exists(string $key): bool :是否存在

phpts_kv_list(): array :全部未过期条目

phpts_kv_count(): int :条目数

phpts_kv_clear(): bool :清空

限制与语义:

  • 键 ≤ 64 字节,值 ≤ 64 字节;共 10 万条;按字节计,中文一个字 3 字节。
  • 失败抛异常,文案前缀 phpts_kv:。
  • TTL 惰性过期,没有后台清扫。
  • 存 PHPTS_EVENT_CLIENTID 原值,不要自己加 ws- / tcp- 前缀:自动 ID 本身已带前缀,自报 ID 存原值。
  • WebSocket / TCP 断开时,网关自动删除所有指向该 client_id 的登记;MQTT / 串口没有断开联动,靠 TTL 或手动删除。
  • 网关被独立启动(非 PHPTS 派生)时联动删除静默降级,不影响业务。
  • PHPTS 主程序退出时整区清零;重启后是空表,客户端重连必须重新登记。

登记示例(WebSocket 脚本内):

if (!empty($clientid) && function_exists('phpts_kv_set')) {
    // 业务键建议:user:<id> / device:<sn> / room:<no>
    phpts_kv_set('user:1001', $clientid, 3600);
}

TCP 脚本内:

if (!empty($clientid) && function_exists('phpts_kv_set')) {
    // 真实设备身份通常来自首帧鉴权,例如 "AUTH <sn>"
    if (preg_match('/^AUTH\s+([A-Za-z0-9_-]{1,40})$/', trim($frame), $m)) {
        phpts_kv_set('device:' . $m[1], $clientid, 0); // 0 = 不自动过期,靠断开联动删除
        echo "AUTH OK\r\n";
    }
}

phpts_kv 只在本机 PHPTS 派生进程间共享。跨机器请改用 Redis / MySQL 存 业务身份 → client_id,或让 WebSocket 客户端直接用稳定业务 ID 作为 client_id(§6.7)。

6.7 三种推送拓扑

A. 本机 Web 页面 → WebSocket 客户端(最常见)

<?php
require __DIR__ . '/event/push.php';   // phpts_push()

$user = '1001';
$cid  = function_exists('phpts_kv_get') ? phpts_kv_get('user:' . $user) : null;
if (!$cid) {
    http_response_code(409);
    exit('client offline');
}

$r = phpts_push('ws', json_encode([
    'type' => 'notify',
    'data' => ['title' => '新订单', 'order' => 'A20261119001'],
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);

if (!$r['ok']) {
    // 404 = 已离线;0 = 推送接口不可达
    error_log('push failed: ' . $r['status'] . ' ' . $r['body']);
}

B. 跨机器 / 不共享 phpts_kv

让 WebSocket 客户端使用稳定业务 ID 作为握手 client_id:

// 浏览器端
const uid = 'user-1001';   // 只允许 [A-Za-z0-9_.:-]{1,64}
const ws = new WebSocket(`ws://192.168.1.10:3380/chat?client_id=${uid}`);

远端服务器无需查询 KV,直接推:

phpts_push('ws', $json, [
    'client' => 'user-1001',
    'base'   => 'http://192.168.1.10:3379',
    'token'  => '从 PHPTS 界面复制',
]);

TCP 不支持自定义连接 ID,远端只能:

  1. 通过 PHPTS 本机脚本把 tcp-xxxx 写进 Redis/MySQL 再共享;
  2. 或调用 /tcp/clients 拉列表后按业务字段(需要你在首帧里带设备号并自行维护);
  3. 或改成 WebSocket 接入(可直接用稳定 ID)。

C. 事件脚本 → 另一个客户端(联动)

例如设备 A 上报报警,事件脚本把通知推给值班人员的 WebSocket:

// tcp.php 内
if (str_starts_with($cmd, 'ALARM')) {
    $cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:oncall') : null;
    if ($cid) {
        phpts_push('ws', json_encode([
            'type' => 'alarm',
            'from' => $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '',
            'msg'  => $cmd,
        ], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
    }
    echo "ALARM ACK\r\n";
}

注意:向当前正在处理的同一条连接推送也可以,但该帧会排在本次应答之后;不要用这种方式实现「推送先于应答」的协议。

6.8 业务协议建议(强烈推荐)

WebSocket / TCP / MQTT 都建议用统一信封,避免客户端无法区分「应答」和「主动通知」:

{ "v": 1, "type": "ack",    "seq": 12, "ts": 1760000000, "data": { } }
{ "v": 1, "type": "notify", "seq": 13, "ts": 1760000001, "data": { } }
{ "v": 1, "type": "error",  "seq": 14, "ts": 1760000002, "data": { "code": "E_AUTH" } }
  • type 区分 ack / notify / alarm / error;
  • seq 由服务端单调递增(可放 KV 或由客户端回带);
  • ts 统一 Unix 秒;
  • 二进制协议用「长度前缀 + 类型 + 序号 + 载荷」,不要用文本分隔符。

6.9 跨机部署清单

  1. 「(Server → Client)主动推送接口」把监听地址改成 0.0.0.0 或 [::];
  2. 必须设置 Token(32 位十六进制,界面可一键生成);
  3. Windows 防火墙放行该端口(仅限可信网段);
  4. 公网暴露时不要直接开 3379:用 Nginx 反代加 HTTPS、IP 白名单、限流;推送接口本身是明文 HTTP;
  5. 远端代码设置 3 秒超时并处理 status=0(网络不可达);
  6. 远端不要调用 phpts_kv_*;用 Redis/MySQL 或稳定 client_id。

7. 完整闭环示例

7.1 WebSocket 登记 + Web 推送

规则配置(「WebSocket 服务器」Tab):

路径:/chat

PHP 脚本:wwwroot/event/ws.php

超时:0(继承全局)

wwwroot/event/ws.php:

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
require_once __DIR__ . '/push.php';

$raw      = file_get_contents('php://input');
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$clientip = $_SERVER['PHPTS_EVENT_CLIENTIP'] ?? '';

if (trim($raw) === 'QUIT') {
    echo '__PHPTS_CLOSE__';
    return;
}

$msg = json_decode($raw, true);
if (!is_array($msg)) {
    $msg = ['raw' => $raw];
}

// 登录/订阅:客户端发 {"type":"bind","uid":"1001"}
if (($msg['type'] ?? '') === 'bind' && !empty($msg['uid']) && function_exists('phpts_kv_set')) {
    phpts_kv_set('user:' . preg_replace('/[^A-Za-z0-9_-]/', '', (string)$msg['uid']), $clientid, 3600);
}

echo json_encode([
    'v'     => 1,
    'type'  => 'ack',
    'from'  => $clientid,
    'ip'    => $clientip,
    'recv'  => $msg,
    'ts'    => time(),
], JSON_UNESCAPED_UNICODE);

wwwroot/send.php(Nginx 站点里的普通页面):

<?php
require __DIR__ . '/event/push.php';

$uid = preg_replace('/[^A-Za-z0-9_-]/', '', $_POST['uid'] ?? '');
$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:' . $uid) : null;
if (!$cid) {
    exit(json_encode(['ok' => false, 'error' => 'offline'], JSON_UNESCAPED_UNICODE));
}

$r = phpts_push('ws', json_encode([
    'v'    => 1,
    'type' => 'notify',
    'data' => ['text' => $_POST['text'] ?? 'hello'],
    'ts'   => time(),
], JSON_UNESCAPED_UNICODE), ['client' => $cid]);

exit(json_encode(['ok' => $r['ok'], 'upstream' => $r['status']], JSON_UNESCAPED_UNICODE));

浏览器端:

const ws = new WebSocket('ws://127.0.0.1:3380/chat?client_id=user-1001');
ws.onopen = () => ws.send(JSON.stringify({ type: 'bind', uid: '1001' }));
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'notify') console.log('通知', msg.data);
};

7.2 TCP 设备命令下发

TCP 脚本 wwwroot/event/tcp.php:

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
require_once __DIR__ . '/push.php';

$frame    = file_get_contents('php://input');
$clientid = $_SERVER['PHPTS_EVENT_CLIENTID'] ?? '';
$cmd      = trim($frame);

if (preg_match('/^AUTH\s+([A-Za-z0-9_-]{1,40})$/', $cmd, $m)) {
    if (function_exists('phpts_kv_set')) {
        phpts_kv_set('device:' . $m[1], $clientid, 0); // 断开由网关自动删
    }
    echo "AUTH OK\r\n";
    return;
}
if ($cmd === 'QUIT') {
    echo '__PHPTS_CLOSE__';
    return;
}
if ($cmd === 'PING') {
    echo "PONG\r\n";
    return;
}

echo "OK\r\n";

Web 端下发命令:

$r = phpts_push('tcp', "SET 1\r\n", ['key' => 'device:sn-001']);
// 或直接:['client' => 'tcp-0000000a']

7.3 串口主动写入

// 已由「串口监听」规则打开 COM3 时才能推
$r = phpts_push('serial', "\xAA\x55\x01\x00", ['port' => 'COM3']);
if (!$r['ok'] && $r['status'] === 404) {
    error_log('COM3 未打开或规则未启动');
}

7.4 定时器定时推送

规则:mode=daily,at=08:30,脚本 wwwroot/event/morning.php,附加参数 job=morning。

<?php
ini_set('display_errors', '0');
error_reporting(E_ALL);
date_default_timezone_set('Asia/Shanghai');
require_once __DIR__ . '/push.php';

$cid = function_exists('phpts_kv_get') ? phpts_kv_get('user:1001') : null;
if ($cid) {
    $r = phpts_push('ws', json_encode([
        'v'    => 1,
        'type' => 'notify',
        'data' => ['text' => '早上好,今日待办已生成'],
        'ts'   => time(),
    ], JSON_UNESCAPED_UNICODE), ['client' => $cid]);
    error_log('morning push: ' . $r['status'] . ' ' . $r['body']);
} else {
    error_log('morning push: user:1001 offline');
}

echo 'done' . PHP_EOL; // 只进网关日志

7.5 客户端侧最少要做什么

WebSocket:用稳定业务 ID 作 client_id;浏览器会自动回 Pong,自研客户端必须实现 Pong;断线后指数退避重连,并在重连后重新 bind/拉取缺失数据

TCP:连接后先发鉴权帧(如 AUTH <sn>);网关没有应用层心跳,长连接建议自己加 PING/PONG;重连后重新鉴权登记

串口:设备侧按约定帧格式解析;推送写入与事件应答共用同一条串口,设备要能区分主动下发与应答

MQTT:客户端自行订阅;reply_topic 的通配展开由网关完成,客户端只需订具体主题

推送接口没有离线队列:客户端离线期间的消息不会补发。重连后的数据一致性由业务自己保证(推荐「重连 → 拉快照 → 再增量」)。

8. 自检与排障

8.1 上线前自检

# 1) 语法检查(在 PHPTS 安装目录执行;php.exe 在 apps\php8.5\)
"apps\php8.5\php.exe" -l "wwwroot\event\ws.php"

# 2) 任务池端口
Test-NetConnection 127.0.0.1 -Port 6285

# 3) 推送接口与 Token
curl.exe -s "http://127.0.0.1:3379/ws/clients"
curl.exe -s -H "X-PHPTS-Token: <token>" "http://127.0.0.1:3379/ws/clients"

# 4) 定向推送(在线返回 ok;离线返回 404)
curl.exe -s -X POST -H "X-PHPTS-Token: <token>" --data-binary "hello" "http://127.0.0.1:3379/ws/send?client=user-1001"

# 5) 查看网关日志
Get-Content "logs\phpts-event-$(Get-Date -Format yyyy-MM-dd).log" -Tail 50

8.2 症状 → 原因 → 处理

客户端发消息后没有任何回包
常见原因:任务池未启动 / 脚本路径错 / 脚本 fatal
处理:启动任务池;确认脚本相对 base 的路径;看网关日志

WS 收到空帧
常见原因:脚本没有任何 echo
处理:明确输出内容;要关连接用 __PHPTS_CLOSE__

WS 收到乱码/JSON 解析失败
常见原因:PHP Warning/Notice 混入输出、文件有 BOM
处理:脚本头 ini_set('display_errors','0');文件存为 UTF-8 无 BOM

__PHPTS_CLOSE__ 不生效
常见原因:输出被 JSON 包装、拼接或加了引号
处理:只输出该字符串本身

推送返回 404
常见原因:客户端已离线 / ID 错 / 子服务已停
处理:先 /ws/clients 或 /tcp/clients 核对;等待重连

推送返回 403
常见原因:Token 错或没带
处理:用 X-PHPTS-Token 头,值与界面一致

推送返回 0(连不上)
常见原因:推送接口停止 / 地址端口错 / 防火墙
处理:启动推送接口;核对 [pushapi];本机先用 127.0.0.1

推送返回 400 empty payload
常见原因:正文为空;GET 便捷形式没带 text=/data=
处理:传非空正文,或补 text=/data=

推送返回 413
常见原因:请求体 > 1MB
处理:拆包或改走文件/对象存储,只推 URL

TCP 一帧被拆成两帧
常见原因:idle 窗口小于帧内停顿
处理:调小 idle_ms,或改用 line/none

TCP 两帧被合并
常见原因:对端连发快、无静默;或用了 none
处理:改用 line;idle 下无法区分无静默的连续帧

串口收到的数据带 \n
常见原因:串口 line 模式帧内含分隔符
处理:脚本 rtrim($frame, "\r\n")

串口打不开 / 启动即异常
常见原因:COM 口被调试助手或其它程序占用
处理:关闭占用程序;或换 COM 口

定时器不触发或重复触发
常见原因:mode/at/weekdays/days 配错;防重入关闭
处理:核对规则;保持 no_reentry=1 或做幂等

跨机推送不通
常见原因:监听仍是 127.0.0.1 / 防火墙未放行
处理:改 0.0.0.0 或 [::];放行端口;设 Token

跨机调 phpts_kv_get() 报主程序未运行
常见原因:非 PHPTS 派生进程
处理:改用 Redis/MySQL 或稳定 client_id

8.3 日志位置

网关日志(含 PHP stderr):<base>/logs/phpts-event-YYYY-MM-DD.log

任务池 PHP 错误:同上(stderr 被网关收集);也可在脚本里 error_log()

脚本自定义日志:建议放脚本同目录,用 __DIR__ 拼

9. 安全清单

  1. Token 必须设,尤其是监听地址不是 127.0.0.1 时。
  2. 推送接口不要直接暴露公网;必须跨公网时用 HTTPS 反代 + IP 白名单 + 限流。
  3. WebSocket 可在首条消息里做鉴权:客户端带 token,脚本校验失败就输出 __PHPTS_CLOSE__。
  4. TCP 首帧鉴权:校验设备 SN/密钥后再登记 phpts_kv,未通过直接断开。
  5. 所有外部输入都要限长、限字符集;不要 eval、不要拼接 shell 命令。
  6. 文件路径必须由服务端白名单生成,禁止把客户端传来的路径直接拼进 __DIR__。
  7. 日志写入注意并发与轮转,不要把用户输入原样写进可执行上下文。
  8. phpts_kv 键值都有 64 字节上限;业务 ID 先哈希或截断,避免异常。

10. AI 交付物模板

当用户要求「实现一个事件触发任务」时,最终回答应包含以下五部分:

  1. 脚本文件清单:每个文件的完整路径(相对 PHPTS base)与完整代码。
  2. 规则配置表:

WebSocket 服务器
规则名:chat
路径/端口/主题/COM:/chat
PHP 脚本:wwwroot/event/ws.php
分帧:—
超时:0
其它:心跳默认开

TCP 服务器
规则名:device
路径/端口/主题/COM:59301
PHP 脚本:wwwroot/event/tcp.php
分帧:idle / 50ms
超时:0
其它:—

  1. 客户端示例:浏览器/设备端如何连接、如何带 client_id、如何重连。
  2. 自检步骤:php -l、端口探测、curl 推送、日志路径。
  3. 需要人工确认的项:任务池是否启动、子服务是否启动、推送 Token、监听地址、防火墙。

不要只给代码而不给规则配置;事件脚本离开规则配置无法运行。

11. 版本与特性时间线

共用推送接口 /ws/send、/tcp/send :2026-11-10

PHPTS_EVENT_CLIENTIP 客户端 IP:2026-11-12

phpts_kv 断开自动清理:2026-11-12

推送接口独立启停 + /serial/ 端点:2026-11-13 / 2026-11-14

多目标推送、key= 直达、limit/total :2026-11-15

__PHPTS_CLOSE__ 主动关闭连接:2026-11-16

定时器 daily/weekly/monthly + no_reentry :2026-11-16

全局 fcgi_timeout 默认 300 秒:2026-11-17

如果目标环境早于上表,先做能力探测:

  • 推送:curl /ws/clients 是否 200;
  • 关闭约定:脚本输出 __PHPTS_CLOSE__ 后客户端是否收到 close;
  • KV:function_exists('phpts_kv_set');
  • 多目标/key=:响应里是否出现 sent/missing。

12. 一页速查

事件正文        file_get_contents('php://input')
定时器参数      $_GET
规则名          $_SERVER['PHPTS_EVENT_NAME']
连接 ID         $_SERVER['PHPTS_EVENT_CLIENTID']
客户端 IP       $_SERVER['PHPTS_EVENT_CLIENTIP']
本次超时        $_SERVER['PHPTS_EVENT_TIMEOUT']
关闭连接        echo '__PHPTS_CLOSE__';
错误日志        error_log() / 文件,禁止 echo 调试
WS 回包         text 帧;空输出=空帧
TCP 回包        原始字节;空输出=不写回
MQTT 回包       发布到 reply_topic
串口回包        仅 echo=1 时写回
主动推送        POST http://127.0.0.1:3379/{ws|tcp|serial}/send
目标参数        client= / client_id=(逗号多值);串口 port=(别名 client=)
空正文          400 empty payload(GET 便捷形式用 text= 或 data=)
广播            POST /{ws|tcp|serial}/broadcast
在线列表        GET /ws/clients  GET /tcp/clients  GET /serial/ports
鉴权            ?token= 或 X-PHPTS-Token
业务 ID 登记    phpts_kv_set('user:1001', $clientid, 3600)
断开自动清理    WS/TCP 由网关自动按 client_id 删除登记

Markdown 原文下载: event-ai-guide-zh.md

Comments 0 comments

No comments yet. Be the first to comment.

Leave a comment

Comments are plain text only. HTML and URLs are not allowed.

Your email will not be displayed in comments