WebSocket Server Configuration

The Swoole WebSocket Server is a sub-class of the base TCP/UDP Server, so you have access to certain server configuration options as well, read the main server configuration options to see what you have access to.

The following configuration options are only available to you when running a WebSocket server, these options are additions to the main server configuration. The Swoole WebSocket Server is an implementation of the WebSocket protocol using the TCP/UDP server base class/service.

Setting Configuration Options

Here is a quick working example of setting WebSocket server configuration options using the set() method:

<?php

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

$server = new Server('127.0.0.1', 9501);

// Remember you have access to main server options as well
$server->set([
  'websocket_compression' => true,
  // ...
  ]);

$server->on('Message', function(Server $server, Frame $frame)
{
    $server->push(
        $frame->fd,
        'Hello World, from Swoole!',
        SWOOLE_WEBSOCKET_OPCODE_TEXT,
        SWOOLE_WEBSOCKET_FLAG_FIN | SWOOLE_WEBSOCKET_FLAG_COMPRESS
    );
});

$server->start();

websocket_subprotocol

Set the WebSocket sub-protocol.

After setting the handshake response HTTP requests, the header Sec-WebSocket-Protocol is used to request a subprotocol. Please refer to the specific WebSocket protocol related RFC documents or refer to the Mozilla Guide on Subprotocols.

A WebSocket Subprotocol is used to establish structure between the client and server, it is purely server side and allows the client to request a certain protocol in the header, for example:

GET /chat HTTP/1.1
...
Sec-WebSocket-Protocol: soap, wamp

<?php
$server->set([
    'websocket_subprotocol' => 'my-chat-protocol-v1',
]);

open_websocket_close_frame

Enable or disable the WebSocket closed frame object and protocol. The OpCode for a closed frame request is WEBSOCKET_OPCODE_CLOSE (aka 0x08). By default this is false and can be turned on to enable close frame objects in the Message event callback.

After enabling the server Message event callback will receive frame objects.

See the documentation for Closed Frame

<?php
$server->set([
    'open_websocket_close_frame' => true,
]);

open_websocket_ping_frame

Enable or disable WebSocket ping protocol frames. By default this option is false. If enabled the server Message event callback can receive ping requests and allow you to handle the response (pong) instead of Swoole handling this automatically.

The OpCode for a ping request is WEBSOCKET_OPCODE_PING (aka 0x9).

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

Example of handling your own ping detection and pong response from server to client:

<?php
$server = new Swoole\WebSocket\Server("127.0.0.1", 9501);

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

$server->on('Open', function(Swoole\WebSocket\Server $server, $request)
{
  // ...
});

$server->on('Message', function(Swoole\WebSocket\Server $server, $frame)
{
    // WEBSOCKET_OPCODE_PING (aka 0x9)
    if($frame->opcode == 0x09)
    {
        echo "Ping frame received: Code {$frame->opcode}\n";

        // Reply to Pong frame, creating new response frame
        $pongFrame = new Swoole\WebSocket\Frame;
        $pongFrame->opcode = WEBSOCKET_OPCODE_PONG;

        // Push response of pong to client using a frame object
        $server->push($frame->fd, $pongFrame);
    }
    else
    {
        echo "Message received: {$frame->data}\n";
    }
});

$server->on('Close', function($server, $fd)
{
  // ...
});

$server->start();

Since v4.5.4

open_websocket_pong_frame

Enable or disable the open use of pong events. By default this option is set to false. If enabled it allows you to manually control the pong frame event, handle when a client sends a pong frame to the server. If this option is false, Swoole will automatically handle pong frames being sent to the server.

A pong frame OpCode is WEBSOCKET_OPCODE_PONG (aka 0x10).

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

<?php
$server = new Swoole\WebSocket\Server("127.0.0.1", 9501);

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

$server->on('Open', function(Swoole\WebSocket\Server $server, $request)
{
  // ...
});

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

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

$server->start();

Since v4.5.4

websocket_compression

Enable or disable WebSocket data Compression.

If set to true the data frame will use zlib for compression, it depends if the client can support WebSocket compression, so it may not always be used, even if enabled. The server will give time specifically to check if compression is supported in accordance with WebSocket RFC-7692.

After enabling the option for compression, during the WebSocket handshake, compression support is validated then then you can use the SWOOLE_WEBSOCKET_FLAG_COMPRESS flag to compress specific data frames, a frame is only compressed when using that flag.

For a complete example, see the WebSocket Compression Example.

<?php
$server->set([
    'websocket_compression' => true,
]);

Since v4.4.12