Socket.io 服务

Socket.io 是一款非常流行的应用层实时通讯协议和框架，可以轻松实现应答、分组、广播。hyperf/socketio-server 支持了 Socket.io 的 WebSocket 传输协议。

安装

  1. composer require hyperf/socketio-server

hyperf/socketio-server 组件是基于 WebSocket 实现的，请确保服务端已经添加了 WebSocket 服务 的配置。

  1. // config/autoload/server.php
  2. [
  3.     'name' => 'socket-io',
  4.     'type' => Server::SERVER_WEBSOCKET,
  5.     'host' => '0.0.0.0',
  6.     'port' => 9502,
  7.     'sock_type' => SWOOLE_SOCK_TCP,
  8.     'callbacks' => [
  9.         Event::ON_HAND_SHAKE => [Hyperf\WebSocketServer\Server::class, 'onHandShake'],
  10.         Event::ON_MESSAGE => [Hyperf\WebSocketServer\Server::class, 'onMessage'],
  11.         Event::ON_CLOSE => [Hyperf\WebSocketServer\Server::class, 'onClose'],
  12.     ],
  13. ],

快速开始

服务端

  1. <?php
  3. declare(strict_types=1);
  5. namespace App\Controller;
  7. use Hyperf\SocketIOServer\Annotation\Event;
  8. use Hyperf\SocketIOServer\Annotation\SocketIONamespace;
  9. use Hyperf\SocketIOServer\BaseNamespace;
  10. use Hyperf\SocketIOServer\Socket;
  11. use Hyperf\Utils\Codec\Json;
  13. /**
  14.  * @SocketIONamespace("/")
  15.  */
  16. class WebSocketController extends BaseNamespace
  17. {
  18.     /**
  19.      * @Event("event")
  20.      * @param string $data
  21.      */
  22.     public function onEvent(Socket $socket, $data)
  23.     {
  24.         // 应答
  25.         return 'Event Received: ' . $data;
  26.     }
  28.     /**
  29.      * @Event("join-room")
  30.      * @param string $data
  31.      */
  32.     public function onJoinRoom(Socket $socket, $data)
  33.     {
  34.         // 将当前用户加入房间
  35.         $socket->join($data);
  36.         // 向房间内其他用户推送（不含当前用户）
  37.         $socket->to($data)->emit('event', $socket->getSid() . "has joined {$data}");
  38.         // 向房间内所有人广播（含当前用户）
  39.         $this->emit('event', 'There are ' . count($socket->getAdapter()->clients($data)) . " players in {$data}");
  40.     }
  42.     /**
  43.      * @Event("say")
  44.      * @param string $data
  45.      */
  46.     public function onSay(Socket $socket, $data)
  47.     {
  48.         $data = Json::decode($data);
  49.         $socket->to($data['room'])->emit('event', $socket->getSid() . " say: {$data['message']}");
  50.     }
  51. }

每个 socket 会自动加入以自己 sid 命名的房间（$socket->getSid()），发送私聊信息就推送到对应 sid 即可。

框架会自动触发 connect 和 disconnect 两个事件。

客户端

由于服务端只实现了 WebSocket 通讯，所以客户端要加上 {transports:["websocket"]} 。

  1. <script src="https://cdn.bootcss.com/socket.io/2.3.0/socket.io.js"></script>
  2. <script>
  3.     var socket = io('ws://127.0.0.1:9502', { transports: ["websocket"] });
  4.     socket.on('connect', data => {
  5.         socket.emit('event', 'hello, hyperf', console.log);
  6.         socket.emit('join-room', 'room1', console.log);
  7.         setInterval(function () {
  8.             socket.emit('say', '{"room":"room1", "message":"Hello Hyperf."}');
  9.         }, 1000);
  10.     });
  11.     socket.on('event', console.log);
  12. </script>

API 清单

Socket API

通过 SocketAPI 对目标 Socket 进行推送，或以目标 Socket 的身份在房间内发言。需要在事件回调中使用。

  1. <?php
  2. /**
  3.  * @Event("SomeEvent")
  4.  */
  5. function onSomeEvent(\Hyperf\SocketIOServer\Socket $socket){
  7.   // sending to the client
  8.   // 向连接推送 hello 事件
  9.   $socket->emit('hello', 'can you hear me?', 1, 2, 'abc');
  11.   // sending to all clients except sender
  12.   // 向所有连接推送 broadcast 事件，但是不包括当前连接。
  13.   $socket->broadcast->emit('broadcast', 'hello friends!');
  15.   // sending to all clients in 'game' room except sender
  16.   // 向 game 房间内所有连接推送 nice game 事件，但是不包括当前连接。
  17.   $socket->to('game')->emit('nice game', "let's play a game");
  19.   // sending to all clients in 'game1' and/or in 'game2' room, except sender
  20.   // 向 game1 房间 和 game2 房间内所有连接取并集推送 nice game 事件，但是不包括当前连接。
  21.   $socket->to('game1')->to('game2')->emit('nice game', "let's play a game (too)");
  23.   // WARNING: `$socket->to($socket->getSid())->emit()` will NOT work, as it will send to everyone in the room
  24.   // named `$socket->getSid()` but the sender. Please use the classic `$socket->emit()` instead.
  25.   // 注意：自己给自己推送的时候不要加to，因为$socket->to()总是排除自己。直接$socket->emit()就好了。
  27.   // sending with acknowledgement
  28.   // 发送信息，并且等待并接收客户端响应。
  29.   $reply = $socket->emit('question', 'do you think so?')->reply();
  31.   // sending without compression
  32.   // 无压缩推送
  33.   $socket->compress(false)->emit('uncompressed', "that's rough");
  34. }

全局 API

直接从容器中获取 SocketIO 单例。这个单例可向全局广播或指定房间、个人通讯。未指定命名空间时，默认使用 ‘/‘ 空间。

  1. <?php
  2. $io = \Hyperf\Utils\ApplicationContext::getContainer()->get(\Hyperf\SocketIOServer\SocketIO::class);
  4. // sending to all clients in 'game' room, including sender
  5. // 向 game 房间内的所有连接推送 bigger-announcement 事件。
  6. $io->in('game')->emit('big-announcement', 'the game will start soon');
  8. // sending to all clients in namespace 'myNamespace', including sender
  9. // 向 /myNamespace 命名空间下的所有连接推送 bigger-announcement 事件
  10. $io->of('/myNamespace')->emit('bigger-announcement', 'the tournament will start soon');
  12. // sending to a specific room in a specific namespace, including sender
  13. // 向 /myNamespace 命名空间下的 room 房间所有连接推送 event 事件
  14. $io->of('/myNamespace')->to('room')->emit('event', 'message');
  16. // sending to individual socketid (private message)
  17. // 向 socketId 单点推送
  18. $io->to('socketId')->emit('hey', 'I just met you');
  20. // sending to all clients on this node (when using multiple nodes)
  21. // 向本机所有连接推送
  22. $io->local->emit('hi', 'my lovely babies');
  24. // sending to all connected clients
  25. // 向所有连接推送
  26. $io->emit('an event sent to all connected clients');

命名空间 API

和全局 API 一样，只不过已经限制了命名空间。

  1. // 以下伪码等价
  2. $foo->emit();
  3. $io->of('/foo')->emit();
  5. /**
  6.  * class内使用也等价
  7.  * @SocketIONamespace("/foo")
  8.  */
  9. class FooNamespace extends BaseNamespace {
  10.     public function onEvent(){
  11.         $this->emit(); 
  12.         $this->io->of('/foo')->emit();
  13.     }
  14. }

进阶教程

设置 Socket.io 命名空间

Socket.io 通过自定义命名空间实现多路复用。（注意：不是 PHP 的命名空间）

  1. 可以通过 @SocketIONamespace("/xxx") 将控制器映射为 xxx 的命名空间，

  2. 也可通过

  1. <?php
  2. use Hyperf\SocketIOServer\Collector\SocketIORouter;
  3. use App\Controller\WebSocketController;
  4. SocketIORouter::addNamespace('/xxx' , WebSocketController::class);

在路由中添加。

开启 Session

安装并配置好 hyperf/session 组件及其对应中间件，再通过 SessionAspect 切入 SocketIO 来使用 Session 。

  1. <?php
  2. // config/autoload/aspect.php
  3. return [
  4.     \Hyperf\SocketIOServer\Aspect\SessionAspect::class,
  5. ];

Swoole 4.4.17 及以下版本只能读取 HTTP 创建好的 Cookie，Swoole 4.4.18 及以上版本可以在 WebSocket 握手时创建 Cookie

调整房间适配器

默认的房间功能通过 Redis 适配器实现，可以适应多进程乃至分布式场景。

  1. 可以替换为内存适配器，只适用于单 worker 场景。
  1. <?php
  2. // config/autoload/dependencies.php
  3. return [
  4.     \Hyperf\SocketIOServer\Room\AdapterInterface::class => \Hyperf\SocketIOServer\Room\MemoryAdapter::class,
  5. ];
  1. 可以替换为空适配器，不需要房间功能时可以降低消耗。
  1. <?php
  2. // config/autoload/dependencies.php
  3. return [
  4.     \Hyperf\SocketIOServer\Room\AdapterInterface::class => \Hyperf\SocketIOServer\Room\NullAdapter::class,
  5. ];

调整 SocketID (sid)

默认 SocketID 使用 ServerID#FD 的格式，可以适应分布式场景。

  1. 可以替换为直接使用 Fd 。
  1. <?php
  2. // config/autoload/dependencies.php
  3. return [
  4.     \Hyperf\SocketIOServer\SidProvider\SidProviderInterface::class => \Hyperf\SocketIOServer\SidProvider\LocalSidProvider::class,
  5. ];
  1. 也可以替换为 SessionID 。
  1. <?php
  2. // config/autoload/dependencies.php
  3. return [
  4.     \Hyperf\SocketIOServer\SidProvider\SidProviderInterface::class => \Hyperf\SocketIOServer\SidProvider\SessionSidProvider::class,
  5. ];

其他事件分发方法

  1. 可以手动注册事件，不使用注解。
  1. <?php
  2. declare(strict_types=1);
  4. namespace App\Controller;
  6. use Hyperf\SocketIOServer\BaseNamespace;
  7. use Hyperf\SocketIOServer\SidProvider\SidProviderInterface;
  8. use Hyperf\SocketIOServer\Socket;
  9. use Hyperf\WebSocketServer\Sender;
  11. class WebSocketController extends BaseNamespace
  12. {
  13.     public function __construct(Sender $sender, SidProviderInterface $sidProvider) {
  14.         parent::__construct($sender,$sidProvider);
  15.         $this->on('event', [$this, 'echo']);
  16.     }
  18.     public function echo(Socket $socket, $data)
  19.     {
  20.         $socket->emit('event', $data);
  21.     }
  22. }
  1. 可以在控制器上添加 @Event() 注解，以方法名作为事件名来分发。此时应注意其他公有方法可能会和事件名冲突。
  1. <?php
  2. declare(strict_types=1);
  4. namespace App\Controller;
  6. use Hyperf\SocketIOServer\Annotation\SocketIONamespace;
  7. use Hyperf\SocketIOServer\Annotation\Event;
  8. use Hyperf\SocketIOServer\BaseNamespace;
  9. use Hyperf\SocketIOServer\Socket;
  11. /**
  12.  * @SocketIONamespace("/")
  13.  * @Event()
  14.  */
  15. class WebSocketController extends BaseNamespace
  16. {
  17.     public function echo(Socket $socket, $data)
  18.     {
  19.         $socket->emit('event', $data);
  20.     }
  21. }

修改 SocketIO 基础参数

框架默认参数：

配置 类型 默认值
$pingTimeout int 100
$pingInterval int 10000
$clientCallbackTimeout int 10000

有时候，由于推送消息比较多或者网络较卡，在 100ms 内，无法及时返回 PONG，就会导致连接断开。这时候我们可以通过以下方式，进行重写：

  1. <?php
  3. declare(strict_types=1);
  5. namespace App\Kernel;
  7. use Hyperf\Contract\StdoutLoggerInterface;
  8. use Hyperf\SocketIOServer\Parser\Decoder;
  9. use Hyperf\SocketIOServer\Parser\Encoder;
  10. use Hyperf\SocketIOServer\SidProvider\SidProviderInterface;
  11. use Hyperf\SocketIOServer\SocketIO;
  12. use Hyperf\WebSocketServer\Sender;
  13. use Psr\Container\ContainerInterface;
  15. class SocketIOFactory
  16. {
  17.     public function __invoke(ContainerInterface $container)
  18.     {
  19.         $io = new SocketIO(
  20.             $container->get(StdoutLoggerInterface::class),
  21.             $container->get(Sender::class),
  22.             $container->get(Decoder::class),
  23.             $container->get(Encoder::class),
  24.             $container->get(SidProviderInterface::class)
  25.         );
  27.         // 重写 pingTimeout 参数
  28.         $io->setPingTimeout(10000);
  30.         return $io;
  31.     }
  32. }

然后在 dependencies.php 添加对应映射即可。

  1. return [
  2.     Hyperf\SocketIOServer\SocketIO::class => App\Kernel\SocketIOFactory::class,
  3. ];

Auth 鉴权

您可以通过使用中间件来拦截 WebSocket 握手，实现鉴权功能，如下：

  1. <?php
  3. declare(strict_types=1);
  5. namespace App\Middleware;
  7. use Psr\Container\ContainerInterface;
  8. use Psr\Http\Message\ResponseInterface;
  9. use Psr\Http\Server\MiddlewareInterface;
  10. use Psr\Http\Message\ServerRequestInterface;
  11. use Psr\Http\Server\RequestHandlerInterface;
  13. class WebSocketAuthMiddleware implements MiddlewareInterface
  14. {
  15.     /**
  16.      * @var ContainerInterface
  17.      */
  18.     protected $container;
  20.     public function __construct(ContainerInterface $container)
  21.     {
  22.         $this->container = $container;
  23.     }
  25.     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
  26.     {
  27.         // 伪代码，通过 isAuth 方法拦截握手请求并实现权限检查
  28.         if (! $this->isAuth($request)) {
  29.             return $this->container->get(\Hyperf\HttpServer\Contract\ResponseInterface::class)->raw('Forbidden');
  30.         }
  32.         return $handler->handle($request);
  33.     }
  34. }

并将上面的中间件配置到对应的 WebSocket Server 中去即可。

获取原始请求对象

连接建立以后，有时需获取客户端 IP ，Cookie 等请求信息。原始请求对象已经被保留在连接上下文中，您可以用如下方式在事件回调中获取：

  1. public function onEvent($socket, $data)
  2. {
  3.     $request = Hyperf\WebSocketServer\Context::get(
  4.         Psr\Http\Message\ServerRequestInterface::class
  5.     );
  6. }

Nginx 代理配置

使用 Nginx 反向代理 Socket.io 与 WebSocket 有些许区别

  1. server {
  2.     location ^~/socket.io/ {
  3.         # 执行代理访问真实服务器
  4.         proxy_pass http://hyperf;
  5.         proxy_http_version 1.1;
  6.         proxy_set_header Host $host;
  7.         proxy_set_header Upgrade $http_upgrade;
  8.         proxy_set_header Connection "upgrade";
  9.         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  10.     }
  11. }