Client • Server • Message • Classes • Examples • Changelog • Contributing
The client can read and write on a WebSocket stream. It internally supports Upgrade handshake and implicit close and ping/pong operations.
Examples
Simple send-receive operation
This example send a single message to a server, and output the response.
$client = new WebSocket\Client("ws://echo.websocket.org/");
$client->text("Hello WebSocket.org!");
echo $client->receive();
$client->close();
Listening to a server
To continuously listen to incoming messages, you need to put the receive operation within a loop. Note that these functions always throw exception on any failure, including recoverable failures such as connection time out. By consuming exceptions, the code will re-connect the socket in 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();
Receiving messages
By default the receive()
method return messages of 'text' and 'binary' opcode.
The filter option allows you to specify which message types to return.
$client = new WebSocket\Client("ws://echo.websocket.org/", ['filter' => ['text']]);
$client->receive(); // Only return 'text' messages
$client = new WebSocket\Client("ws://echo.websocket.org/", ['filter' => ['text', 'binary', 'ping', 'pong', 'close']]);
$client->receive(); // Return all messages
By setting an option, receive()
will instead return a Message instance.
$server = new WebSocket\Server(['return_obj' => true]);
$message = $server->receive();
$message->getOpcode();
$message->getContent();
Sending messages
There are convenience methods to send messages with different opcodes.
$client = new WebSocket\Client("ws://echo.websocket.org/");
// Convenience methods
$client->text('A plain text message'); // Send an opcode=text message
$client->binary($binary_string); // Send an opcode=binary message
$client->ping(); // Send an opcode=ping frame
$client->pong(); // Send an unsolicited opcode=pong frame
// Generic send method
$client->send($payload); // Sent as opcode=text
$client->send($payload, 'binary'); // Sent as opcode=binary
// Message send method
$server->send(new WebSocket\Message\Text($payload)); // Sent as opcode=text
$server->send(new WebSocket\Message\Binary($payload)); // Sent as opcode=text
Constructor options
The $options
parameter in constructor accepts an associative array of options.
context
- A stream context created using stream_context_create.filter
- Array of opcodes to return on receive, default['text', 'binary']
fragment_size
- Maximum payload size. Default 4096 chars.headers
- Additional headers as associative array name => content.logger
- A PSR-3 compatible logger.persistent
- Connection is re-used between requests until time out is reached. Default false.return_obj
- Return a Message instance on receive, default falsetimeout
- Time out in seconds. Default 5 seconds.
$context = stream_context_create();
stream_context_set_option($context, 'ssl', 'verify_peer', false);
stream_context_set_option($context, 'ssl', 'verify_peer_name', false);
$client = new WebSocket\Client("ws://echo.websocket.org/", [
'context' => $context, // Attach stream context created above
'filter' => ['text', 'binary', 'ping'], // Specify message types for receive() to return
'headers' => [ // Additional headers, used to specify subprotocol
'Sec-WebSocket-Protocol' => 'soap',
'origin' => 'localhost',
],
'logger' => $my_psr3_logger, // Attach a PSR3 compatible logger
'return_obj' => true, // Return Message instance rather than just text
'timeout' => 60, // 1 minute time out
]);
Exceptions
WebSocket\BadOpcodeException
- Thrown if provided opcode is invalid.WebSocket\BadUriException
- Thrown if provided URI is invalid.WebSocket\ConnectionException
- Thrown on any socket I/O failure.WebSocket\TimeoutException
- Thrown when the socket experiences a time out.