All documentation

PHPTS 2.0.13 버전 업데이트: 이벤트 트리거 작업 추가

2026년 11월 19일 출시된 PHPTS 2.0.13은 '이벤트 트리거 작업' 모듈을 추가했습니다. WebSocket, TCP, MQTT, 시리얼, 타이머 다섯 가지 이벤트 소스를 내장 Rust 이벤트 게이트웨이에 통합 연결하고, PHP 스크립트가 이벤트를 처리해 원래 경로로 응답합니다. 또한 phpts_kv 프로세스 간 공유 키-값 저장소와 Server → Client 능동 푸시 인터페이스를 제공하여, 일반 PHP 페이지에서도 온라인 클라이언트, TCP 연결 또는 시리얼로 메시지를 능동 푸시할 수 있습니다. 이 글은 3분 만에 시작하기, 스크립트 규약, 능동 푸시 폐쇄 루프, 타이머 재진입 방지 및 다섯 가지 디버깅 도우미 등 세부 사항을 다룹니다.

version

머리말

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 사용률을 최적화했습니다. 숨쉬기(브리딩) LED 애니메이션을 제거하고 정적 표시등을 적용하여 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 연결 또는 직렬 포트로 데이터를 능동적으로 푸시할 수 있습니다. 아래에서 기능과 사용법을 한 번에 설명합니다.

1. 이벤트 트리거 작업이란 무엇인가

모듈은 독립 게이트웨이 프로세스 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 장치 연결, 다중 직렬 포트 동시 모니터링; 보레이트, 데이터 비트, 정지 비트, 패리티 비트를 포트별로 구성 가능; 「응답을 직렬 포트로 쓰기」를 켜면 스크립트 출력이 원본 그대로 장치로 다시 기록되어, 호스트 PC 응답 시나리오에서 바로 사용할 수 있습니다.
  • 타이머: 간격 / 매일 / 매주 / 매월 네 가지 트리거 방식, 「재진입 방지」 스위치(이전 라운드가 끝나지 않았으면 이번 라운드를 건너뛰며 기본 활성화), 추가 매개변수는 QUERY_STRING으로 스크립트에 전달됩니다.

2. 3분 만에 시작하기

  1. 사이드바의 「도구」 그룹에서 「이벤트 트리거 작업」 페이지를 엽니다(개요 대시보드에도 상태 카드와 진입점이 있습니다). 페이지는 총 6개 탭으로 구성됩니다: 「전역 위임 구성 및 푸시 서비스」 + 5개 하위 서비스.
  2. 해당 탭에서 「규칙 추가」를 클릭합니다: WebSocket은 경로, TCP는 포트, MQTT는 토픽, 직렬 포트는 COM 포트, 타이머는 트리거 방식을 입력/선택합니다; 「PHP 스크립트」 열에는 기본적으로 패키지에 포함된 데모 스크립트(data/taskdemo/ 아래 다섯 개 예제)가 미리 채워져 있으며, 「선택…」으로 자신의 스크립트로 다시 바인딩하거나 「편집」을 클릭해 바로 열어 수정할 수 있습니다.
  3. 「시작」을 클릭합니다(먼저 현재 페이지 구성을 자동 저장한 후 서비스를 시작/중지합니다). 페이지 헤더 오른쪽의 디버깅 도우미로 클라이언트에 연결해 메시지를 하나 보내면 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=로 사용자 지정 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 실행 제한 시간과 연동되므로 느린 스크립트가 중간에 끊기지 않습니다.

3. 능동 푸시: 임의의 PHP 페이지에서 온라인 클라이언트로 메시지 보내기

게이트웨이는 HTTP 푸시 인터페이스(기본 127.0.0.1:3379, 독립적 시작/중지 가능, 권한 Token 설정 가능)를 상시 상주시키며, URI 접두사로 전달 대상을 구분합니다: /ws/send(WebSocket text 프레임), /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"

4. 타이머: 네 가지 트리거 방식과 재진입 방지

타이머는 더 이상 「간격 초」 한 가지 형태만 있는 것이 아닙니다: 간격 / 매일 / 매주 / 매월 중 선택 가능하며, 매일/매주/매월은 로컬 벽시계 기준으로 정해진 시각에 트리거됩니다(매주는 요일 선택, 매월은 일자 선택 가능, 2월에 31일이 없으면 자연스럽게 건너뜀). 「재진입 방지」는 규칙별로 구성할 수 있으며, 활성화 시 이전 회차가 반환되지 않으면 이번 회차를 건너뛰고, 비활성화 시 정해진 시각에 평소대로 트리거됩니다. 스크립트 요청 본문은 비어 있고 추가 매개변수는 $_GET으로 전달되며, 출력은 게이트웨이 로그에만 기록되므로 하트비트 보고, 만료 정리, 일일 보고서 생성 등 백그라운드 작업에 적합합니다. 구버전 간격 규칙은 업그레이드 후에도 동작이 문자 그대로 동일합니다.

5. 디버깅 도우미와 신뢰성 세부 사항

  • 다섯 가지 디버깅 도우미: 액티브 푸시 / WebSocket 클라이언트 / TCP 클라이언트 / MQTT / 시리얼, 페이지 헤더 오른쪽에서 원클릭으로 열 수 있으며, 「먼저 연결한 후 푸시」 폐쇄 루프 검증; 팝업은 상단 바 작업 표시줄로 최소화할 수 있고 언제든 세션을 복원할 수 있습니다.
  • 이벤트 트리거 게이트웨이 로그 버튼: 당일 로그를 실시간으로 따라가며(매일 파일 하나), 위임 문제를 조사할 때 디렉터리를 뒤질 필요가 없습니다.
  • 포트 점유 사전 점검: 시작 전에 수신 대기 포트 점유자를 확인하고 지목하여 오류를 보고합니다(bind만 하고 listen하지 않은 숨은 점유 포함). 시리얼 포트도 시작 전에 점유를 사전 점검하며, 먼저 「시리얼 디버깅 도우미」를 자체 프로그램으로 인식한 뒤 다른 프로그램을 판별합니다.
  • 구성 핫 적용: 저장 후 게이트웨이가 즉시 다시 로드되며, 규칙을 수정할 때 프로세스를 재시작할 필요가 없습니다. 중국어 규칙 이름은 그대로 유지됩니다.
  • 프로세스 수준 격리: 단일 하위 서비스가 크래시해도 예외로만 표시되고 게이트웨이 전체가 중단되지 않습니다. 게이트웨이와 작업 풀의 시작/중지 의미는 독립적이며, 페이지에 의존성 안내가 표시됩니다.

6. 기타 업데이트

  • 네트워크 저장소 매핑 / 파일 전송기 대용량 파일 업로드 수정: 로컬 프록시의 PUT 수신을 스트리밍 디스크 기록으로 변경하여, 17GB급 업로드가 「4GB 메모리 벽」에 부딪혀 중간에 실패하지 않습니다. 업로드 취소 경로에 회귀 잠금을 추가하여 전송 중 취소가 즉시 적용됩니다.
  • 이벤트 위임 기본 타임아웃이 30초에서 300초로 조정되어 장시간 작업 스크립트가 더 여유롭게 동작합니다(여전히 전역 / 단일 규칙으로 재정의 가능).

7. 업그레이드 안내

공식 웹사이트에서 2.0.13 설치 패키지를 다운로드하거나 내장 업데이트를 사용해 업그레이드하면 됩니다. 기존 구성은 자동으로 호환됩니다. 「이벤트 트리거 작업」은 현재 beta 표시가 있으며, 사용 중 문제와 제안을 환영합니다.

설치 패키지 다운로드: https://down.phpts.com/phpts.zip

Comments 1 comments

程序老王
太强了!"Rust 网关负责高并发接入、PHP 专注业务处理"这个解耦思路简直是降维打击。之前自己用 Workerman 撸过一套,断线重连、心跳全得手写,bug 修了一个月。现在用 PHPTS 绑个 PHP 脚本就能跑,这哪是工具升级,这是把开发成本直接砍到零啊,真 PHP 开发者的福音。phpts_kv 进程间变量共享 + 主动推送这个组合牛,我把客户端的用户名当key,WebSocket的客户端ID当Value存起来,之后普通 Nginx+PHP 页面也能随时通过短连接,给指定用户的 WebSocket 客户端推消息,等于把长连接能力无缝嵌进了传统 Web 开发流程。

Leave a comment

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

Your email will not be displayed in comments