summaryrefslogtreecommitdiffstats
path: root/vendor/textalk/websocket/docs/Server.md
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/textalk/websocket/docs/Server.md')
-rw-r--r--vendor/textalk/websocket/docs/Server.md136
1 files changed, 136 insertions, 0 deletions
diff --git a/vendor/textalk/websocket/docs/Server.md b/vendor/textalk/websocket/docs/Server.md
new file mode 100644
index 0000000..7d01a41
--- /dev/null
+++ b/vendor/textalk/websocket/docs/Server.md
@@ -0,0 +1,136 @@
+[Client](Client.md) • Server • [Message](Message.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
+
+# Websocket: Server
+
+The library contains a rudimentary single stream/single thread server.
+It internally supports Upgrade handshake and implicit close and ping/pong operations.
+
+Note that it does **not** support threading or automatic association ot continuous client requests.
+If you require this kind of server behavior, you need to build it on top of provided server implementation.
+
+## Class synopsis
+
+```php
+WebSocket\Server {
+
+ public __construct(array $options = [])
+ public __destruct()
+ public __toString() : string
+
+ public accept() : bool
+ public text(string $payload) : void
+ public binary(string $payload) : void
+ public ping(string $payload = '') : void
+ public pong(string $payload = '') : void
+ public send(mixed $payload, string $opcode = 'text', bool $masked = true) : void
+ public receive() : mixed
+ public close(int $status = 1000, mixed $message = 'ttfn') : mixed
+
+ public getPort() : int
+ public getPath() : string
+ public getRequest() : array
+ public getHeader(string $header_name) : string|null
+
+ public getName() : string|null
+ public getPier() : string|null
+ public getLastOpcode() : string
+ public getCloseStatus() : int
+ public isConnected() : bool
+ public setTimeout(int $seconds) : void
+ public setFragmentSize(int $fragment_size) : self
+ public getFragmentSize() : int
+ public setLogger(Psr\Log\LoggerInterface $logger = null) : void
+}
+```
+
+## Examples
+
+### Simple receive-send operation
+
+This example reads a single message from a client, and respond with the same message.
+
+```php
+$server = new WebSocket\Server();
+$server->accept();
+$message = $server->receive();
+$server->text($message);
+$server->close();
+```
+
+### Listening to clients
+
+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.
+
+```php
+$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();
+```
+
+### Filtering received 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.
+
+```php
+$server = new WebSocket\Server(['filter' => ['text']]);
+$server->receive(); // only return 'text' messages
+
+$server = new WebSocket\Server(['filter' => ['text', 'binary', 'ping', 'pong', 'close']]);
+$server->receive(); // return all messages
+```
+
+### Sending messages
+
+There are convenience methods to send messages with different opcodes.
+```php
+$server = new WebSocket\Server();
+
+// Convenience methods
+$server->text('A plain text message'); // Send an opcode=text message
+$server->binary($binary_string); // Send an opcode=binary message
+$server->ping(); // Send an opcode=ping frame
+$server->pong(); // Send an unsolicited opcode=pong frame
+
+// Generic send method
+$server->send($payload); // Sent as masked opcode=text
+$server->send($payload, 'binary'); // Sent as masked opcode=binary
+$server->send($payload, 'binary', false); // Sent as unmasked opcode=binary
+```
+
+## Constructor options
+
+The `$options` parameter in constructor accepts an associative array of options.
+
+* `filter` - Array of opcodes to return on receive, default `['text', 'binary']`
+* `fragment_size` - Maximum payload size. Default 4096 chars.
+* `logger` - A [PSR-3](https://www.php-fig.org/psr/psr-3/) compatible logger.
+* `port` - The server port to listen to. Default 8000.
+* `return_obj` - Return a [Message](Message.md) instance on receive, default false
+* `timeout` - Time out in seconds. Default 5 seconds.
+
+```php
+$server = new WebSocket\Server([
+ 'filter' => ['text', 'binary', 'ping'], // Specify message types for receive() to return
+ 'logger' => $my_psr3_logger, // Attach a PSR3 compatible logger
+ 'port' => 9000, // Listening port
+ 'return_obj' => true, // Return Message insatnce rather than just text
+ 'timeout' => 60, // 1 minute time out
+]);
+```
+
+## Exceptions
+
+* `WebSocket\BadOpcodeException` - Thrown if provided opcode is invalid.
+* `WebSocket\ConnectionException` - Thrown on any socket I/O failure.
+* `WebSocket\TimeoutException` - Thrown when the socket experiences a time out.