PHPTS 2.0.13 版本更新:新增事件觸發任務
2026年11月19日發布的 PHPTS 2.0.13,新增「事件觸發任務」模組:WebSocket、TCP、MQTT、序列埠、計時器五類事件源統一接入內建的 Rust 事件閘道,由 PHP 腳本處理事件並原路回應;搭配 phpts_kv 跨行程共享鍵值儲存與 Server → Client 主動推送介面,任意一般 PHP 頁面都能向線上用戶端、TCP 連線或序列埠主動推送訊息。本文涵蓋三分鐘上手、腳本約定、主動推送閉環、計時器防重入與五個除錯助手等細節。
前言
PHPTS 2.0.13 於2026年11月19日正式發布,安裝包下載網址:https://down.phpts.com/phpts.zip
2.0.13 版本(2026-11-19)更新說明:
- 1、增加「PHP FastCGI(任務)」行程池管理器,一組獨立於 Web 業務的 PHP 8.5 FastCGI 行程池,作為事件處理的專屬引擎。當事件發生時,PHPTS 將任務直接指派給記憶體中待命的 PHP 行程,規避了行程冷啟動開銷,確保了事件處理的高效與即時;
- 2、新增「事件觸發任務」閘道:以 Windows IOCP 非同步非阻塞方式統一承接 WebSocket 長連線、TCP 長連線、MQTT 訂閱、序列埠和秒級計時器等 I/O 事件,閘道透過 FastCGI 將事件投遞到 PHP-CGI 任務行程池,由 PHP 腳本執行具體業務,形成「Rust 閘道負責高併發事件接入與排程、PHP 專注短時業務處理」的解耦架構;用你熟悉的 PHP 腳本處理每一條事件——不用自己寫 socket 伺服器,不用維護常駐 PHP 行程,連線管理、分幀、心跳、TLS 全部交給內建的 Rust 事件閘道;
- 3、新增 phpts_kv 行程間共享鍵值儲存 PHP 擴充功能,結合(Server → Client)主動推播介面,一般 Nginx + PHP 網站頁面也能隨時向線上的指定 WebSocket、TCP 用戶端、或序列埠主動推播資料;
- 4、最佳化 CPU 使用率,移除呼吸燈動畫,改用靜態指示燈,UI 無變化時,GPU 行程的 CPU 佔用降到 0%;
- 5、頂部工作列服務狀態指示燈,換成用戶端工具圖示,支援滑鼠長按,左右拖曳變更位置;
- 6、左側工作清單、工具清單,支援滑鼠長按,上下拖曳變更位置;
- 7、修正電子郵局第三方 IMAP 用戶端連結刪除郵件失敗的 BUG;
- 8、修正檔案傳輸器大檔案上傳中斷的 BUG;
- 9、修正 MySQL 資料庫 root 密碼重設失敗的 BUG。
本次版本最大的亮點,是全新模組「事件觸發任務」:將 WebSocket、TCP、MQTT、序列埠、計時器五類事件來源統一接入 PHPTS,用你熟悉的 PHP 腳本處理每一條事件——不用自己寫 socket 伺服器,不用維護常駐 PHP 行程,連線管理、分幀、心跳、TLS 全部交給內建的 Rust 事件閘道。
配合新版的 phpts_kv 行程間共享鍵值儲存擴充功能與(Server → Client)主動推播介面,一般 Nginx + PHP 網站頁面也能隨時向線上用戶端、TCP 連線或序列埠主動推播資料。下面把功能與用法一次講清楚。
一、事件觸發任務是什麼
模組由獨立閘道行程 phpts-event.exe 承載:長連線與事件來源全部由 Rust 持有(WebSocket / TCP 走 IOCP 非同步 I/O),PHP 只是無狀態的邏輯執行單元——每來一條事件,閘道經 FastCGI 協定將它委託給「PHP FastCGI (任務)」行程池執行你綁定的腳本,腳本的輸出沿原路寫回用戶端。單一子服務異常只影響自己,不會拖垮整個閘道。
五個事件來源,各帶獨立啟動 / 停止 / 重新啟動按鈕,可隨 PHPTS 開機自動啟動:
- WebSocket 伺服器:ws:// 與 wss:// 雙監聽,TLS 憑證可在頁面一鍵申請(DNS 驗證)或從憑證庫一鍵部署;伺服器端心跳 Ping 可設定;依「路徑」路由到不同 PHP 腳本。
- TCP 伺服器:多連接埠同時監聽,每個連接埠綁定各自腳本;三種分幀方式——idle 靜默合併(預設 50ms 靜默視窗,可設定)、line 依分隔符號切幀、none 原始位元組段,黏包半包不用自己處理。
- MQTT 訂閱:支援 + / # 萬用主題,可對接內建 NanoMQ 或外部 broker;規則可設定「應答主題」,腳本輸出自動發布回去。
- 序列埠監聽:RS232 / RS485 / TTL 裝置接入,多序列埠同時監聽;波特率、資料位元、停止位元、同位元檢查逐埠可設定;「應答寫回序列埠」開啟後腳本輸出自動原樣寫回裝置,上位機應答場景開箱即用。
- 計時器:間隔 / 每天 / 每週 / 每月四種觸發方式,「防重入」開關(上一輪沒跑完就跳過本輪,預設開啟),附加參數以 QUERY_STRING 傳入腳本。
二、三分鐘上手
- 開啟側邊欄「工具」群組的「事件觸發任務」頁(總覽儀表板也有狀態卡片與入口)。頁面共六個 Tab:「全域委託設定與推播服務」+ 五個子服務。
- 在對應 Tab 點「新增規則」:WebSocket 填路徑、TCP 填連接埠、MQTT 填主題、序列埠選 COM 埠、計時器選觸發方式;「PHP 腳本」欄預設預填隨包示範腳本(data/taskdemo/ 下五個範例),可用「選擇…」換綁自己的腳本,或點「編輯」直接開啟修改。
- 點「啟動」(會先自動儲存本頁設定再啟停服務)。用頁首右側的除錯助手連上用戶端發送一則訊息,即可看到 PHP 腳本的應答原路返回。
腳本端的約定非常簡單:php://input 讀取事件正文,$_SERVER['PHPTS_EVENT_*'] 取得中繼資料,echo 輸出即應答。範例(WebSocket 路由腳本):
<?php
// 讀取用戶端送來的整則訊息(JSON 與純文字雙相容)
$msg = file_get_contents('php://input');
$data = json_decode($msg, true);
if (json_last_error() !== JSON_ERROR_NONE) { $data = ['text' => $msg]; }
// 以業務名稱為鍵,將目前連線 ID 登記至共享記憶體,供 Web 頁面稍後主動推送
if (function_exists('phpts_kv_set')) {
phpts_kv_set('user:1001', $_SERVER['PHPTS_EVENT_CLIENTID'], 3600);
}
// 用戶端要求退出:輸出約定值,閘道主動關閉這條連線(close 1000)
if (($data['cmd'] ?? '') === 'QUIT') { echo '__PHPTS_CLOSE__'; return; }
// 輸出即應答:作為 text 幀沿原連線發回用戶端
echo json_encode(['type' => 'reply', 'msg' => 'received']);
可用中繼資料一覽:
- PHPTS_EVENT_CLIENTID:目前連線 ID(WebSocket / TCP)。用戶端握手可帶 ?client_id= 自訂身分,不帶則自動分配 ws- / tcp- 前綴 ID。
- PHPTS_EVENT_CLIENTIP:用戶端 IP(不含連接埠),做存取控制、稽核日誌直接用。
- PHPTS_EVENT_PATH / PHPTS_EVENT_NAME:命中的路由路徑 / 規則名稱(規則名稱支援中文)。
- PHPTS_EVENT_PORT:TCP 監聽連接埠或序列埠名稱;PHPTS_EVENT_TOPIC:MQTT 實際命中的主題。
兩個實用約定:WebSocket / TCP 腳本輸出恰好等於 __PHPTS_CLOSE__ 時,閘道主動關閉目前連線(驗證失敗、用戶端 QUIT 等情境統一收尾);逾時為「全域 + 單一規則」兩層,單一規則 0 = 繼承全域(預設 300 秒),並連動任務池的 PHP 執行時限,慢腳本不會被半路中斷。
三、主動推播:任意 PHP 頁面都能向線上用戶端發送訊息
閘道常駐一個 HTTP 推送介面(預設 127.0.0.1:3379,可獨立啟停、可設定權限 Token),依 URI 前綴區分投遞目標:/ws/send(WebSocket 文字幀)、/tcp/send(TCP 原始位元組)、/serial/send(序列埠原始位元組),三者均支援 broadcast 廣播與線上清單查詢;指定目標支援逗號分隔多個 ID,還支援 key= 直接傳入 phpts_kv 鍵,閘道自動查鍵取 ID 投遞。
典型閉環:事件腳本裡用 phpts_kv_set('user:1001', 連線ID) 登記(phpts_kv 是基於 Windows 具名共享記憶體的跨行程鍵值儲存擴充功能,Web 池與任務池預設開啟);此後任何一般 PHP 頁面、定時腳本憑鍵取 ID 推送;用戶端斷線時閘道自動刪除共享記憶體裡的登記,腳本無需操心下線清理。
<?php
// 任意一般 PHP 頁面 / 定時腳本:依登記推送
$client = phpts_kv_get('user:1001');
if (!$client) { exit('client offline'); } // 已斷線(閘道已自動刪除)或 TTL 到期
$url = 'http://127.0.0.1:3379/ws/send?client=' . urlencode($client) . '&token=你的权限Token';
$ctx = stream_context_create(['http' => [
'method' => 'POST',
'header' => "Content-Type: text/plain\r\n",
'content' => json_encode(['type' => 'notify', 'msg' => 'hello']),
'timeout' => 3,
]]);
echo file_get_contents($url, false, $ctx); // {"ok":true}
命令列同樣方便(頁面「全域委託設定與推送服務」Tab 內有依目前設定即時拼接的 curl 範例,可一鍵複製):
curl -X POST "http://127.0.0.1:3379/ws/send?client=ws-1a2b3c4d&token=你的权限Token" -d "hello" curl -X POST "http://127.0.0.1:3379/ws/broadcast?token=你的权限Token" -d "系统公告" curl -X POST "http://127.0.0.1:3379/serial/send?port=COM3" --data-binary "@frame.bin"
四、定時器:四種觸發方式與防重入
定時器不再只有「間隔秒」一種形態:間隔 / 每天 / 每週 / 每月任選,每天/每週/每月依本地時間到點觸發(每週可選星期、每月可選幾號,2 月沒有 31 號自然跳過);「防重入」可逐規則設定,開啟時上一輪未返回即跳過本輪,關閉則到點照常觸發。腳本請求主體為空、附加參數走 $_GET,輸出只寫入閘道日誌,適合心跳回報、過期清理、日報生成等背景作業。舊版間隔規則升級後行為逐字不變。
五、偵錯助手與可靠性細節
- 五個偵錯助手:主動推送 / WebSocket 用戶端 / TCP 用戶端 / MQTT / 序列埠,頁首右側一鍵開啟,「先連上、再推送」閉環驗證;彈窗可最小化到頂欄工作列,隨時恢復工作階段。
- 事件觸發閘道日誌按鈕:即時跟隨當天日誌(每天一個檔案),排查委託問題不用翻目錄。
- 連接埠占用預檢:啟動前查詢監聽連接埠的占用者並點名報錯(含僅 bind 未 listen 的隱蔽占用);序列埠啟動前預檢占用,先認「序列埠偵錯助手」自己人,再判斷其他程式。
- 設定熱生效:儲存後閘道即時重新載入,改規則不用重新啟動行程;中文規則名原樣保留。
- 行程級隔離:單一子服務崩潰只標示異常不團滅閘道;閘道與任務池啟停語意獨立,頁面有相依提示。
六、其他更新
- 網路儲存映射 / 檔案傳輸器大檔案上傳修復:本機代理 PUT 接收改為串流寫入磁碟,17GB 級上傳不再撞「4GB 記憶體牆」中途失敗;上傳取消鏈路補上回歸鎖,傳輸中取消即時生效。
- 事件委託預設逾時由 30 秒調整為 300 秒,長任務腳本更從容(仍可全域 / 單規則覆寫)。
七、升級說明
官網下載 2.0.13 安裝包或使用內建更新升級即可,舊設定自動相容。「事件觸發任務」目前帶 beta 標識,歡迎在使用中回饋問題與建議。
Comments 1 comments