textalk/websocket-php

By default, the receive() method on a WebSocket\Client or WebSocket\Server returns a string. To receive structured WebSocket\Message\Message instances instead, you must set the return_obj option to true during instantiation.

When enabled, the returned object will be an instance of a specific class corresponding to the WebSocket opcode:

• WebSocket\Message\Text
• WebSocket\Message\Binary
• WebSocket\Message\Ping
• WebSocket\Message\Pong
• WebSocket\Message\Close

$client = new WebSocket\Client('ws://example.com/', ['return_obj' => true]);
$message = $client->receive(); // Returns a Message object

The WebSocket\Server is a rudimentary single-stream, single-threaded server. It handles the WebSocket Upgrade handshake, implicit close operations, and ping/pong operations automatically.

Important Limitations:

• It does not support threading.
• It does not support automatic association of continuous client requests.

If you require multi-threaded behavior or complex client management, you must build a custom implementation on top of this server.

By default, receive() only returns messages with text or binary opcodes. You can change this behavior by passing a filter array in the constructor options. Supported opcodes include text, binary, ping, pong, and close.

// Only return 'text' messages
$server = new WebSocket\Server(['filter' => ['text']]);
$server->receive();

// Return all message types
$server = new WebSocket\Server(['filter' => ['text', 'binary', 'ping', 'pong', 'close']]);
$server->receive();

In development environments where dev dependencies are installed via Composer, you can use EchoLogger to print library information synchronously to the console. This is useful for debugging client and server interactions. For production environments, you should replace this with a proper logging implementation.

namespace WebSocket;

$logger = new EchoLogger();

$client = new Client('ws://echo.websocket.org/');
$client->setLogger($logger);

$server = new Server();
$server->setLogger($logger);

To continuously listen for incoming messages, wrap the receive() call in a loop. Because the client throws exceptions on any failure (including recoverable ones like timeouts), you should wrap the operation in a try-catch block. Catching WebSocket\ConnectionException allows you to handle errors and attempt a reconnection in the next loop iteration.

$client = new WebSocket\Client("ws://echo.websocket.org/");
while (true) {
    try {
        $message = $client->receive();
        // Act on received message
        // Break while loop to stop listening
    } catch (\WebSocket\ConnectionException $e) {
        // Possibly log errors
    }
}
$client->close();

To create a persistent server that listens for multiple clients, wrap the accept() method in a while loop.

Error Handling: The server methods throw exceptions on any failure, including recoverable ones like connection timeouts. You must wrap the receive() call in a try...catch block for WebSocket\ConnectionException. Consuming these exceptions allows the loop to continue and attempt to re-connect or accept the next client in the next iteration.

$server = new WebSocket\Server();
while ($server->accept()) {
    try {
        $message = $server->receive();
        // Act on received message
        // Break while loop to stop listening
    } catch (\WebSocket\ConnectionException $e) {
        // Possibly log errors
    }
}
$server->close();

The preferred way to install this library is using Composer.

PHP Version Compatibility:

• PHP ^7.4 or ^8.0: Use the latest version.
• PHP 7.2 or 7.3: Use version 1.5.
• PHP 7.1: Use version 1.4.
• PHP ^5.4 or 7.0: Use version 1.3.

composer require textalk/websocket

The WebSocket\Server constructor accepts an associative array of configuration options:

$server = new WebSocket\Server([
    'filter' => ['text', 'binary', 'ping'],
    'logger' => $my_psr3_logger,
    'port' => 9000,
    'return_obj' => true,
    'timeout' => 60,
]);

To start accepting connections, call accept(). Note that this implementation is blocking; calling accept() will disconnect existing connections and focus on the new incoming request.

Once a connection is established, you can use receive() to read messages. receive() is also a blocking operation that reads from the first available connection. It will return:

• The message content (string) if return_obj is false.
• A Message instance if return_obj is true.
• null if a close opcode is received or if the connection is lost.

You can check the type of the last received message using getLastOpcode().

$server = new Server(['port' => 8000]);
$server->accept();

while ($message = $server->receive()) {
    echo "Received: " . $message . "\n";
    $server->send("Echo: " . $message);
}

To connect to a WebSocket server, instantiate the WebSocket\Client class with a ws:// or wss:// URI. You can optionally pass an associative array of configuration options.

Available Options:

• context: A valid PHP stream context.
• timeout: Socket timeout in seconds (default: 5).
• fragment_size: Size of message fragments in bytes (default: 4096).
• headers: An associative array of HTTP headers to include in the handshake.
• logger: A PSR-3 compatible logger instance.
• persistent: Boolean indicating if the connection should be persistent (default: false).
• return_obj: Boolean; if true, receive() returns the message object instead of the content (default: false).

use WebSocket\Client;

$client = new Client('ws://echo.websocket.org', [
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer my-token',
    ],
]);