WebSocket\Server

通过内置的 WebSocket 服务器支持，通过几行 PHP 代码就可以写出一个异步 IO 的多进程的 WebSocket 服务器。

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);

$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
    echo "server: handshake success with fd{$request->fd}\n";
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    echo "receive from {$frame->fd}:{$frame->data},opcode:{$frame->opcode},fin:{$frame->finish}\n";
    $server->push($frame->fd, "this is server");
});

$server->on('close', function ($server, $fd) {
    echo "client {$fd} closed\n";
});

$server->start();

• 客户端

• Chrome/Firefox/ 高版本 IE/Safari 等浏览器内置了 JS 语言的 WebSocket 客户端

• 微信小程序开发框架内置的 WebSocket 客户端

• 异步 IO 的 PHP 程序中可以使用 Swoole\Coroutine\Http 作为 WebSocket 客户端

• Apache/PHP-FPM 或其他同步阻塞的 PHP 程序中可以使用 swoole/framework 提供的同步 WebSocket 客户端

• 非 WebSocket 客户端不能与 WebSocket 服务器通信

• 如何判断连接是否为 WebSocket 客户端

通过使用 $server->connection_info($fd) 获取连接信息，返回的数组中有一项为 websocket_status，根据此状态可以判断是否为 WebSocket 客户端。

事件

WebSocket 服务器除了接收 Swoole\Server 和 Swoole\Http\Server 基类的回调函数外，额外增加了 3 个回调函数设置。其中：

• onMessage 回调函数为必选

• onOpen 和 onHandShake 回调函数为可选

onHandShake

WebSocket 建立连接后进行握手。WebSocket 服务器会自动进行 handshake 握手的过程，如果用户希望自己进行握手处理，可以设置 onHandShake 事件回调函数。

onHandShake(Swoole\Http\Request $request, Swoole\Http\Response $response);

• 提示

• onHandShake 事件回调是可选的

• 设置 onHandShake 回调函数后不会再触发 onOpen 事件，需要应用代码自行处理，可以使用 $server->defer 调用 onOpen 逻辑

• onHandShake 中必须调用 response->status() 设置状态码为 101 并调用 response->end() 响应，否则会握手失败.

• 内置的握手协议为 Sec-WebSocket-Version: 13，低版本浏览器需要自行实现握手

• 注意

如果需要自行处理 handshake 的时候，再设置这个回调函数。如果不需要 “自定义” 握手过程，那么不要设置该回调，使用 Swoole 默认的握手即可。下面是 “自定义”handshake 事件回调函数中必须要具备的：

$server->on('handshake', function (\Swoole\Http\Request $request, \Swoole\Http\Response $response) {
    // print_r( $request->header );
    // if (如果不满足我某些自定义的需求条件，那么返回end输出，返回false，握手失败) {
    //    $response->end();
    //     return false;
    // }

    // websocket握手连接算法验证
    $secWebSocketKey = $request->header['sec-websocket-key'];
    $patten = '#^[+/0-9A-Za-z]{21}[AQgw]==$#';
    if (0 === preg_match($patten, $secWebSocketKey) || 16 !== strlen(base64_decode($secWebSocketKey))) {
        $response->end();
        return false;
    }
    echo $request->header['sec-websocket-key'];
    $key = base64_encode(
        sha1(
            $request->header['sec-websocket-key'] . '258EAFA5-E914-47DA-95CA-C5AB0DC85B11',
            true
        )
    );

    $headers = [
        'Upgrade' => 'websocket',
        'Connection' => 'Upgrade',
        'Sec-WebSocket-Accept' => $key,
        'Sec-WebSocket-Version' => '13',
    ];

    // WebSocket connection to 'ws://127.0.0.1:9502/'
    // failed: Error during WebSocket handshake:
    // Response must not include 'Sec-WebSocket-Protocol' header if not present in request: websocket
    if (isset($request->header['sec-websocket-protocol'])) {
        $headers['Sec-WebSocket-Protocol'] = $request->header['sec-websocket-protocol'];
    }

    foreach ($headers as $key => $val) {
        $response->header($key, $val);
    }

    $response->status(101);
    $response->end();
});

设置 onHandShake 回调函数后不会再触发 onOpen 事件，需要应用代码自行处理，可以使用 $server->defer 调用 onOpen 逻辑

$server->on('handshake', function (\Swoole\Http\Request $request, \Swoole\Http\Response $response) {
    // 省略了握手内容
    $response->status(101);
    $response->end();

    global $server;
    $fd = $request->fd;
    $server->defer(function () use ($fd, $server)
    {
      echo "Client connected\n";
      $server->push($fd, "hello, welcome\n");
    });
});

onOpen

当 WebSocket 客户端与服务器建立连接并完成握手后会回调此函数。

onOpen(Swoole\WebSocket\Server $server, Swoole\Http\Request $request);

• 提示

• $request 是一个 HTTP 请求对象，包含了客户端发来的握手请求信息

• onOpen 事件函数中可以调用 push 向客户端发送数据或者调用 close 关闭连接

• onOpen 事件回调是可选的

onMessage

当服务器收到来自客户端的数据帧时会回调此函数。

onMessage(Swoole\WebSocket\Server $server, Swoole\WebSocket\Frame $frame)

• 提示

• $frame 是 Swoole\WebSocket\Frame 对象，包含了客户端发来的数据帧信息

• onMessage 回调必须被设置，未设置服务器将无法启动

• 客户端发送的 ping 帧不会触发 onMessage，底层会自动回复 pong 包，也可设置 open_websocket_ping_frame 参数手动处理

• Swoole\WebSocket\Frame $frame

$frame->data 如果是文本类型，编码格式必然是 UTF-8，这是 WebSocket 协议规定的

• OPCode 与数据类型

onRequest

WebSocket\Server 继承自 Http\Server，所以 Http\Server 提供的所有 API 和配置项都可以使用。请参考 Http\Server 章节。

• 设置了 onRequest 回调，WebSocket\Server 也可以同时作为 HTTP 服务器

• 未设置 onRequest 回调，WebSocket\Server 收到 HTTP 请求后会返回 HTTP 400 错误页面

• 如果想通过接收 HTTP 触发所有 WebSocket 的推送，需要注意作用域的问题，面向过程请使用 global 对 WebSocket\Server 进行引用，面向对象可以把 WebSocket\Server 设置成一个成员属性

面向过程代码

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
    echo "server: handshake success with fd{$request->fd}\n";
});
$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    echo "receive from {$frame->fd}:{$frame->data},opcode:{$frame->opcode},fin:{$frame->finish}\n";
    $server->push($frame->fd, "this is server");
});
$server->on('close', function ($server, $fd) {
    echo "client {$fd} closed\n";
});
$server->on('request', function (Swoole\Http\Request $request, Swoole\Http\Response $response) {
    global $server;//调用外部的server
    // $server->connections 遍历所有websocket连接用户的fd，给所有用户推送
    foreach ($server->connections as $fd) {
        // 需要先判断是否是正确的websocket连接，否则有可能会push失败
        if ($server->isEstablished($fd)) {
            $server->push($fd, $request->get['message']);
        }
    }
});
$server->start();

class WebSocketTest
{
    public $server;

    public function __construct()
    {
        $this->server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
        $this->server->on('open', function (Swoole\WebSocket\Server $server, $request) {
            echo "server: handshake success with fd{$request->fd}\n";
        });
        $this->server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
            echo "receive from {$frame->fd}:{$frame->data},opcode:{$frame->opcode},fin:{$frame->finish}\n";
            $server->push($frame->fd, "this is server");
        });
        $this->server->on('close', function ($ser, $fd) {
            echo "client {$fd} closed\n";
        });
        $this->server->on('request', function ($request, $response) {
            // 接收http请求从get获取message参数的值，给用户推送
            // $this->server->connections 遍历所有websocket连接用户的fd，给所有用户推送
            foreach ($this->server->connections as $fd) {
                // 需要先判断是否是正确的websocket连接，否则有可能会push失败
                if ($this->server->isEstablished($fd)) {
                    $this->server->push($fd, $request->get['message']);
                }
            }
        });
        $this->server->start();
    }
}

new WebSocketTest();

onDisconnect(Swoole\WebSocket\Server $server, $fd)

Swoole\WebSocket\Server->push(int $fd, string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, bool $finish = true): bool

// v4.4.12版本改为了flags参数
Swoole\WebSocket\Server->push(int $fd, string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, int $flags = SWOOLE_WEBSOCKET_FLAG_FIN): bool

Swoole\WebSocket\Server->exist(int $fd): bool

Swoole\WebSocket\Server::pack(string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, bool $finish = true, bool $mask = false): string // v4.4.12版本改为了flags参数 
Swoole\WebSocket\Server::pack(string $data, int $opcode = WEBSOCKET_OPCODE_TEXT, int $flags = SWOOLE_WEBSOCKET_FLAG_FIN): string

$ws = new Swoole\Server('127.0.0.1', 9501 , SWOOLE_BASE);

$ws->set(array(
    'log_file' => '/dev/null'
));

$ws->on('WorkerStart', function (\Swoole\Server $serv) {
});

$ws->on('receive', function ($serv, $fd, $threadId, $data) {
    $sendData = "HTTP/1.1 101 Switching Protocols\r\n";
    $sendData .= "Upgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: IFpdKwYy9wdo4gTldFLHFh3xQE0=\r\n";
    $sendData .= "Sec-WebSocket-Version: 13\r\nServer: swoole-http-server\r\n\r\n";
    $sendData .= Swoole\WebSocket\Server::pack("hello world\n");
    $serv->send($fd, $sendData);
});

$ws->start();

Swoole\WebSocket\Server::unpack(string $data): Swoole\WebSocket\Frame|false;

Swoole\WebSocket\Server->disconnect(int $fd, int $code = SWOOLE_WEBSOCKET_CLOSE_NORMAL, string $reason = ''): bool

Swoole\WebSocket\Server->isEstablished(int $fd): bool

常量

数据帧类型

连接状态

选项

WebSocket\Server 是 Server 的子类，可以使用 Server->set() 方法传入配置选项，设置某些参数。

websocket_subprotocol

设置 WebSocket 子协议。

设置后握手响应的 HTTP 头会增加 Sec-WebSocket-Protocol: {$websocket_subprotocol}。具体使用方法请参考 WebSocket 协议相关 RFC 文档。

$server->set([     'websocket_subprotocol' => 'chat', ]);

open_websocket_close_frame

启用 WebSocket 协议中关闭帧（opcode 为 0x08 的帧）在 onMessage 回调中接收，默认为 false。

开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的关闭帧，开发者可自行对其进行处理。

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_close_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0x08) {
        echo "Close frame received: Code {$frame->code} Reason {$frame->reason}\n";
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($server, $fd) {
});

$server->start();

open_websocket_ping_frame

启用 WebSocket 协议中 Ping 帧（opcode 为 0x09 的帧）在 onMessage 回调中接收，默认为 false。

开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的 Ping 帧，开发者可自行对其进行处理。

Swoole 版本 >= v4.5.4 可用

$server->set([     'open_websocket_ping_frame' => true, ]);

值为 false 时底层会自动回复 Pong 帧，但如果设为 true 后则需要开发者自行回复 Pong 帧。

• 示例

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_ping_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0x09) {
        echo "Ping frame received: Code {$frame->opcode}\n";
        // 回复 Pong 帧
        $pongFrame = new Swoole\WebSocket\Frame;
        $pongFrame->opcode = WEBSOCKET_OPCODE_PONG;
        $server->push($frame->fd, $pongFrame);
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($server, $fd) {
});

$server->start();

open_websocket_pong_frame

启用 WebSocket 协议中 Pong 帧（opcode 为 0x0A 的帧）在 onMessage 回调中接收，默认为 false。

开启后，可在 Swoole\WebSocket\Server 中的 onMessage 回调中接收到客户端或服务端发送的 Pong 帧，开发者可自行对其进行处理。

Swoole 版本 >= v4.5.4 可用

$server->set([     'open_websocket_pong_frame' => true, ]);

• 示例

$server = new Swoole\WebSocket\Server("0.0.0.0", 9501);
$server->set(array("open_websocket_pong_frame" => true));
$server->on('open', function (Swoole\WebSocket\Server $server, $request) {
});

$server->on('message', function (Swoole\WebSocket\Server $server, $frame) {
    if ($frame->opcode == 0xa) {
        echo "Pong frame received: Code {$frame->opcode}\n";
    } else {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('close', function ($server, $fd) {
});

$server->start();

websocket_compression

启用数据压缩

为 true 时允许对帧进行 zlib 压缩，具体是否能够压缩取决于客户端是否能够处理压缩（根据握手信息决定，参见 RFC-7692） 需要配合 flags 参数 SWOOLE_WEBSOCKET_FLAG_COMPRESS 来真正地对具体的某个帧进行压缩，具体使用方法见此节

Swoole 版本 >= v4.4.12 可用

其他

相关示例代码可以在 WebSocket 单元测试 中找到

Swoole\WebSocket\Frame

在 v4.2.0 版本中，新增了服务端和客户端发送 Swoole\WebSocket\Frame 对象的支持
在 v4.4.12 版本中，新增了 flags 属性以支持 WebSocket 压缩帧，同时增加了一个新的子类 Swoole\WebSocket\CloseFrame

一个普通的 frame 对象具有以下属性

object(Swoole\WebSocket\Frame)#1 (4) {
  ["fd"]      =>  int(0)
  ["data"]    =>  NULL
  ["opcode"]  =>  int(1)
  ["finish"]  =>  bool(true)
}

Swoole\WebSocket\CloseFrame

一个普通的 close frame 对象具有以下属性，多了 code 和 reason 属性，记录了关闭的错误代码和原因，code 可在 websocket 协议中定义的错误码 查询，reason 若是对端没有明确给出，则为空

如果服务端需要接收 close frame, 需要通过 $server->set 开启 open_websocket_close_frame 参数

object(Swoole\WebSocket\CloseFrame)#1 (6) {
  ["fd"]      =>  int(0)
  ["data"]    =>  NULL
  ["finish"]  =>  bool(true)
  ["opcode"]  =>  int(8)
  ["code"]    =>  int(1000)
  ["reason"]  =>  string(0) ""
}

在用于发送时，fd 属性会被忽略 (因为服务器端 fd 是第一个参数，客户端无需指定 fd)，所以 fd 是一个只读属性

WebSocket 帧压缩 （RFC-7692）

首先你需要配置'websocket_compression' => true 来启用压缩（WebSocket 握手时将与对端交换压缩支持信息）后，你可以使用 flag SWOOLE_WEBSOCKET_FLAG_COMPRESS 来对具体的某个帧进行压缩

示例

• 服务端

use Swoole\WebSocket\Frame;
use Swoole\WebSocket\Server;

$server = new Server('127.0.0.1', 9501);
$server->set(['websocket_compression' => true]);
$server->on('message', function (Server $server, Frame $frame) {
    $server->push(
        $frame->fd,
        'Hello Swoole',
        SWOOLE_WEBSOCKET_OPCODE_TEXT,
        SWOOLE_WEBSOCKET_FLAG_FIN | SWOOLE_WEBSOCKET_FLAG_COMPRESS
    );
    // $server->push($frame->fd, $frame); // 或者 服务端可以直接原封不动转发客户端的帧对象
});
$server->start();

客户端

use Swoole\Coroutine\Http\Client;
use function Swoole\Coroutine\run;

run(function () {
    $cli = new Client('127.0.0.1', 9501);
    $cli->set(['websocket_compression' => true]);
    $cli->upgrade('/');
    $cli->push(
        'Hello Swoole',
        SWOOLE_WEBSOCKET_OPCODE_TEXT,
        SWOOLE_WEBSOCKET_FLAG_FIN | SWOOLE_WEBSOCKET_FLAG_COMPRESS
    );
});

发送 Ping 帧

由于 WebSocket 是长连接，如果一定时间内没有通讯，连接可能会断开。这时候需要心跳机制，WebSocket 协议包含了 Ping 和 Pong 两个帧，可以定时发送 Ping 帧来保持长连接。

示例

• 服务端

use Swoole\WebSocket\Frame;
use Swoole\WebSocket\Server;

$server = new Server('127.0.0.1', 9501);
$server->on('message', function (Server $server, Frame $frame) {
    $pingFrame = new Frame;
    $pingFrame->opcode = WEBSOCKET_OPCODE_PING;
    $server->push($frame->fd, $pingFrame);
});
$server->start();

• 客户端

use Swoole\WebSocket\Frame;
use Swoole\Coroutine\Http\Client;
use function Swoole\Coroutine\run;

run(function () {
    $cli = new Client('127.0.0.1', 9501);
    $cli->upgrade('/');
    $pingFrame = new Frame;
    $pingFrame->opcode = WEBSOCKET_OPCODE_PING;
    // 发送 PING
    $cli->push($pingFrame);
    
    // 接收 PONG
    $pongFrame = $cli->recv();
    var_dump($pongFrame->opcode === WEBSOCKET_OPCODE_PONG);
});