From 5f29b1f1b38a14b0a1bfc442ea3657d06ecd19fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Jensen?= Date: Sat, 29 Oct 2022 14:20:08 +0200 Subject: [PATCH] Documentation --- README.md | 20 +-- docs/Changelog.md | 6 +- docs/Classes/Client.md | 6 - docs/Classes/Connection.md | 6 - docs/Classes/Message.md | 6 - docs/Classes/Server.md | 313 ------------------------------------- docs/Contributing.md | 8 + docs/Message.md | 4 +- 8 files changed, 23 insertions(+), 346 deletions(-) delete mode 100644 docs/Classes/Client.md delete mode 100644 docs/Classes/Connection.md delete mode 100644 docs/Classes/Message.md delete mode 100644 docs/Classes/Server.md diff --git a/README.md b/README.md index 360192f..ab55cf2 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,8 @@ It does not include convenience operations such as listeners and implicit error ## Documentation -- [Client overwiew](docs/Client.md) -- [Server overview](docs/Server.md) -- [Classes](docs/Classes/Classes.md) +- [Client](docs/Client.md) +- [Server](docs/Server.md) - [Examples](docs/Examples.md) - [Changelog](docs/Changelog.md) - [Contributing](docs/Contributing.md) @@ -43,17 +42,18 @@ $client->close(); ## Server -The library contains a websocket [server](docs/Server.md). +The library contains a rudimentary single stream/single thread [server](docs/Server.md). It internally supports Upgrade handshake and implicit close and ping/pong operations. -Preferred operation is using the listener function, but optional operations exist. + +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. ```php $server = new WebSocket\Server(); -$server->listen(function ($message, $connection = null) { - echo "Got {$message->getContent()}\n"; - if (!$connection) return; // Current connection is closed - $connection->text('Sending message to client'); -}); +$server->accept(); +$message = $server->receive(); +$server->text($message); +$server->close(); ``` ### License and Contributors diff --git a/docs/Changelog.md b/docs/Changelog.md index 3763731..c9e086a 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -8,11 +8,11 @@ ### `1.6.0` * Connection separate from Client and Server (@sirn-se) - * getPier() deprecated, replaces by getRemoteName() (@sirn-se) - * Client accepts Psr\Http\Message\UriInterface as input for URI:s (@sirn-se) + * getPier() deprecated, replaced by getRemoteName() (@sirn-se) + * Client accepts `Psr\Http\Message\UriInterface` as input for URI:s (@sirn-se) * Bad URI throws exception when Client is instanciated, previously when used (@sirn-se) - * Major internal refactoring (@sirn-se) * Preparations for multiple conection and listeners (@sirn-se) + * Major internal refactoring (@sirn-se) ## `v1.5` diff --git a/docs/Classes/Client.md b/docs/Classes/Client.md deleted file mode 100644 index 1e825d8..0000000 --- a/docs/Classes/Client.md +++ /dev/null @@ -1,6 +0,0 @@ -Classes: [Client](Client.md) • Server - -# Client class - -Websocket Client class. - diff --git a/docs/Classes/Connection.md b/docs/Classes/Connection.md deleted file mode 100644 index a1e8bc1..0000000 --- a/docs/Classes/Connection.md +++ /dev/null @@ -1,6 +0,0 @@ -Classes: [Client](Client.md) • Server - -# Connection class - -Websocket Connection class. - diff --git a/docs/Classes/Message.md b/docs/Classes/Message.md deleted file mode 100644 index 3989647..0000000 --- a/docs/Classes/Message.md +++ /dev/null @@ -1,6 +0,0 @@ -Classes: [Client](Client.md) • Server - -# Message class - -Websocket Message class. - diff --git a/docs/Classes/Server.md b/docs/Classes/Server.md deleted file mode 100644 index a1f9e33..0000000 --- a/docs/Classes/Server.md +++ /dev/null @@ -1,313 +0,0 @@ -Classes: [Client](Client.md) • Server - -# Server class - -Websocket Server class. Support multiple connections through the `listen()` method. - -## Class synopsis - -```php -WebSocket\Server implements Psr\Log\LoggerAwareInterface { - - // Magic methods - public __construct(array $options = []) - public __toString() : string - - // Server operations - public listen(Closure $callback) : mixed - public stop(): void - - // Server option functions - public getPort() : int - public setTimeout(int $seconds) : void - public setFragmentSize(int $fragment_size) : self - public getFragmentSize() : int - - // Connection broadcast operations - 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 close(int $status = 1000, mixed $message = 'ttfn') : void - public disconnect() : void - public receive() : mixed - - // Provided by Psr\Log\LoggerAwareTrait - public setLogger(Psr\Log\LoggerInterface $logger) : void - - // Deprecated functions - public accept() : bool - public getPath() : string - public getRequest() : array - public getHeader(string $header_name) : string|null - public getLastOpcode() : string - public getCloseStatus() : int - public isConnected() : bool - public getName() : string|null - public getPeer() : string|null - public getPier() : string|null -} -``` - -## __construct - -Constructor for Websocket Server. - -#### Description - -```php -public function __construct(array $options = []) -``` - -#### Parameters - -###### `options` - -An optional array of parameters. -Name | Type | Default | Description ---- | --- | --- | --- -filter | array | ["text", "binary"] | Array of opcodes to return on receive and listen functions -fragment_size | int | 4096 | Maximum payload size -logger | Psr\Log\LoggerInterface | Psr\Log\NullLogger |A [PSR-3](https://www.php-fig.org/psr/psr-3/) compatible logger -port | int | 8000 | The server port to listen to -return_obj | bool | false | Return a [Message](Message.md) instance on receive function -timeout | int | 5 | Time out in seconds - -#### Return Values - -Returns a new WebSocket\Server instance. - -#### Errors/Exceptions - -Emits [ConnectionException](ConnectionException.md) on failure. - -#### Examples - -```php - 8080, 'timeout' => 60]); - -?> -``` - - -## __toString - -Get string representation of instance. - -#### Description - -```php -public function __toString() : string -``` - -#### Return Values - -Returns a string to represent current instance. - - -## listen - -Set server to listen to incoming requests. - -#### Description - -```php -public function listen(Closure $callback) : mixed -``` - -#### Parameters - -###### `callback` - -A callback function that is triggered whenever the server receives a message matching the filter. - -The callback takes two parameters; -* The [Message](Message/Message.md) that has been received -* The [Connection](Connection.md) the server has receievd on, can be `null` if connection is closed - -If callback function returns non-null value, the listener will halt and return that value. -Otherwise it will continue listening and propagating messages. - -#### Return Values - -Returns any non-null value returned by callback function. - -#### Errors/Exceptions - -Emits [ConnectionException](ConnectionException.md) on failure. - -#### Examples - -Minimal setup that continuously listens to incoming text and binary messages. -```php -listen(function ($message, $connection) { - echo $message->getContent(); -}); -?> -``` - -Listen to all incoming message types and respond with a text message. -```php - ['text', 'binary', 'ping', 'pong', 'close']]); -$server->listen(function ($message, $connection) { - if (!$connection) { - $connection->text("Confirm " . $message->getOpcode()); - } -}); -?> -``` - -Halt listener and return a value to calling code. -```php -listen(function ($message, $connection) { - return $message->getContent(); -}); -echo $content; -?> -``` - -## stop - -Tell server to stop listening to incoming requests. - -#### Description - -```php -public function stop(): void -``` - -#### Examples - -Use stop() in listener. -```php -listen(function ($message, $connection) use ($server) { - echo $message->getContent(); - $server->stop(); - }); - // Do things, listener will be restarted in next loop. -} -?> -``` - -## getPort - -#### Description - -```php -public function getPort(): void -``` - -## setTimeout - -#### Description - -```php -public function setTimeout(int $seconds): void -``` - -## setFragmentSize - -#### Description - -```php -public function setFragmentSize(int $fragment_size): self -``` - -## getFragmentSize - -#### Description - -```php -public function getFragmentSize(): int -``` - -## text - -#### Description - -```php -public function text(string $payload) : void -``` - -## binary - -#### Description - -```php -public function binary(string $payload) : void -``` - -## ping - -#### Description - -```php -public function ping(string $payload = '') : void -``` - -## pong - -#### Description - -```php -public function pong(string $payload = '') : void -``` - -## send - -#### Description - -```php -public function send(mixed $payload, string $opcode = 'text', bool $masked = true) : void -``` - -## close - -#### Description - -```php -public function close(int $status = 1000, mixed $message = 'ttfn') : void -``` - -## disconnect - -#### Description - -```php -public function disconnect() : void -``` - -## receive - -#### Description - -```php -public function receive() : mixed -``` - -## setLogger - -#### Description - -```php -public setLogger(Psr\Log\LoggerInterface $logger) : void -``` diff --git a/docs/Contributing.md b/docs/Contributing.md index 263d868..21ed01d 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -12,6 +12,14 @@ Requirements on pull requests; * Code coverage **MUST** remain at 100%. * Code **MUST** adhere to PSR-1 and PSR-12 code standards. +Base your patch on corresponding version branch, and target that version branch in your pull request. + +* `v1.6-master` current version +* `v1.5-master` previous version, bug fixes only +* `v1.4-master` previous version, bug fixes only +* Older versions should not be target of pull requests + + ## Dependency management Install or update dependencies using [Composer](https://getcomposer.org/). diff --git a/docs/Message.md b/docs/Message.md index c6ced83..80df04a 100644 --- a/docs/Message.md +++ b/docs/Message.md @@ -14,7 +14,7 @@ Available classes correspond to opcode; Additionally; * WebSocket\Message\Message - abstract base class for all messages above -* WebSocket\Message\Factory - Factory class to create Msssage instances +* WebSocket\Message\Factory - Factory class to create Message instances ## Message abstract class synopsis @@ -38,7 +38,7 @@ WebSocket\Message\Message { ```php WebSocket\Message\Factory { - public create(string $opcode, string $payload = '') : Message + public create(string $opcode, string $payload = '') : Message; } ```