PHP连接WebSocket需依赖第三方库，日志关键在打点位置、内容精简与防丢失；textalk/websocket可通过继承拦截send/receive并捕获异常；异步场景须用线程安全日志并带连接ID；握手失败优先查HTTP状态码、Sec-WebSocket-Accept及SSL配置。
PHP 本身不原生支持 WebSocket 客户端长连接（fsockopen 或 stream_socket_client 可连，但无法处理 WebSocket 协议握手和帧解析），所以「PHP 连接 WebSocket」几乎总是依赖第三方库（如 textalk/websocket、ratchet/pawl 或 reactphp/socket + 自定义协议层）。日志记录的关键不在“怎么写 log”，而在于「在哪打点、打什么、怎么避免日志爆炸或丢失」。
用 textalk/websocket 时如何注入日志逻辑
这是最轻量、最常用的同步 WebSocket 客户端库。它不内置日志，但所有关键动作都可通过继承或包装 WebSocket 类来拦截：
- 重写
send()方法，在调用父类前记录发送内容（注意截断大消息，避免日志撑爆磁盘） - 在
receive()返回前记录原始响应帧（含opcode、payload length），这对排查粘包/截断问题极有用 - 捕获
WebSocketException，并记录$e->getMessage()和$e->getTraceAsString()的前 200 字符（全 trace 太长，且含敏感上下文）
示例：在 send 前加日志
use WebSocket\Client;
class LoggedClient extends Client {
private $logger;
public function __construct($url, array $options = [], $logger = null) {
parent::__construct($url, $options);
$this->logger = $logger ?: error_log(...);
}
public function send($message) {
$this->logger("WS SEND: " . (strlen($message) > 100 ? substr($message, 0, 100).'...' : $message));
return parent::send($message);
}
}
用 reactphp + clue/reactphp-buzz 做异步连接时的日志陷阱
异步场景下，日志顺序和上下文极易错乱。常见错误是直接在 on('data') 回调里调用 file_put_contents —— 多个并发连接会互相覆盖或阻塞主线程。
立即学习“PHP免费学习笔记（深入）”；
- 必须用线程安全的日志方式：
error_log()（底层是系统 syslog 或 stderr）或Monolog配合StreamHandler并启用useLocking - 每个连接需带唯一 ID（比如用
spl_object_hash($connection)），否则无法区分哪条 log 属于哪个 socket - 不要在
on('error')中记录完整Exception对象 —— React 的错误常含循环引用，var_export会卡死
关键参数：确保 StreamHandler 初始化时传 ['locking' => true]，否则高并发下日志行会错位或丢失。
WebSocket 握手失败时，该查哪几行日志
90% 的连接失败不是代码问题，而是握手阶段被拦截。重点检查以下位置的日志输出：
-
HTTP status code：非101 Switching Protocols就说明没升级成功（可能是 Nginx 没配proxy_http_version 1.1和Upgrade头） -
Sec-WebSocket-Accept值是否与客户端计算一致（可用在线工具校验，不一致说明服务端签名算法被篡改或中间件修改了响应体） - SSL 层日志：若用
wss://，要确认 PHP 的stream_context是否设置了'ssl' => ['verify_peer' => false]（开发可关，生产必须开且配对 CA）
一个典型错误信息：WebSocket connection to 'wss://xxx' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED —— 这说明 TCP 层就失败了，此时 PHP 日志里根本不会出现任何 WebSocket 相关记录，得去查服务器端口监听状态（netstat -tuln | grep :443）和防火墙规则。
真正难的不是记日志，而是让每条日志能回答一个问题：是网络问题？协议问题？还是业务数据触发了服务端主动断连？把 Connection-ID、Timestamp、Opcode、HTTP Status 这四样固定打在每条 log 开头，比堆砌 trace 有用得多。
