Messages

README.md

@@ -12,6 +12,7 @@ It does not include convenience operations such as listeners and implicit error
 
 - [Client](docs/Client.md)
 - [Server](docs/Server.md)
+- [Message](docs/Message.md)
 - [Examples](docs/Examples.md)
 - [Changelog](docs/Changelog.md)
 - [Contributing](docs/Contributing.md)

docs/Changelog.md

@@ -1,4 +1,4 @@
-[Client](Client.md) • [Server](Server.md) • [Examples](Examples.md) • Changelog • [Contributing](Contributing.md)
+[Client](Client.md) • [Server](Server.md) • [Message](Message.md) • [Examples](Examples.md) • Changelog • [Contributing](Contributing.md)
 
 # Websocket: Changelog
 
@@ -9,6 +9,7 @@
 ### `1.5.0`
 
  * Convenience send methods; text(), binary(), ping(), pong() (@sirn-se)
+ * Optional Message instance as receive() method return (@sirn-se)
  * Opcode filter for receive() method (@sirn-se)
  * Fix for unordered framgemented messages (@sirn-se)
  * Various code re-write (@sirn-se)

docs/Client.md

@@ -1,4 +1,4 @@
-Client • [Server](Server.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
+Client • [Server](Server.md) • [Message](Message.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
 
 # Websocket: Client
 
@@ -105,6 +105,7 @@ The `$options` parameter in constructor accepts an associative array of options.
 * `headers` - Additional headers as associative array name => content.
 * `logger` - A [PSR-3](https://www.php-fig.org/psr/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 false
 * `timeout` - Time out in seconds. Default 5 seconds.
 
 ```php

docs/Contributing.md

@@ -1,4 +1,4 @@
-[Client](Client.md) • [Server](Server.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • Contributing
+[Client](Client.md) • [Server](Server.md) • [Message](Message.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • Contributing
 
 # Websocket: Contributing
 

docs/Examples.md

@@ -1,4 +1,4 @@
-[Client](Client.md) • [Server](Server.md) • Examples • [Changelog](Changelog.md) • [Contributing](Contributing.md)
+[Client](Client.md) • [Server](Server.md) • [Message](Message.md) • Examples • [Changelog](Changelog.md) • [Contributing](Contributing.md)
 
 # Websocket: Examples
 

docs/Message.md

@@ -0,0 +1,58 @@
+[Client](Client.md) • [Server](Server.md) • Message • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
+
+# Websocket: Messages
+
+If option `return_obj` is set to `true` on [client](Client.md) or [server](Server.md),
+the `receive()` method will return a Message instance instead of a string.
+
+Available classes correspond to opcode;
+* WebSocket\Message\Text
+* WebSocket\Message\Binary
+* WebSocket\Message\Ping
+* WebSocket\Message\Pong
+* WebSocket\Message\Close
+
+Additionally;
+* WebSocket\Message\Message - abstract base class for all messages above
+* WebSocket\Message\Factory - Factory class to create Msssage instances
+
+##  Message abstract class synopsis
+
+```php
+WebSocket\Message\Message {
+
+    public __construct(string $payload = '')
+    public __toString() : string
+
+    public getOpcode() : string
+    public getLength() : int
+    public getContent() : string
+    public setContent(string $payload = '') : void
+    public hasContent() : bool
+}
+```
+
+##  Factory class synopsis
+
+```php
+WebSocket\Message\Factory {
+
+    public create(string $opcode, string $payload = '') : Message
+}
+```
+
+## Example
+
+Receving a Message and echo some methods.
+
+```php
+$client = new WebSocket\Client('ws://echo.websocket.org/', ['return_obj' => true]);
+$client->text('Hello WebSocket.org!');
+// Echo return same message as sent
+$message = $client->receive();
+echo $message->getOpcode(); // -> "text"
+echo $message->getLength(); // -> 20
+echo $message->getContent(); // -> "Hello WebSocket.org!"
+echo $message->hasContent(); // -> true
+$client->close();
+```

docs/Server.md

@@ -1,4 +1,4 @@
-[Client](Client.md) • Server • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
+[Client](Client.md) • Server • [Message](Message.md) • [Examples](Examples.md) • [Changelog](Changelog.md) • [Contributing](Contributing.md)
 
 # Websocket: Server
 
@@ -113,6 +113,7 @@ The `$options` parameter in constructor accepts an associative array of options.
 * `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 instance on receive, default false
 * `timeout` - Time out in seconds. Default 5 seconds.
 
 ```php

lib/Base.php

@@ -12,6 +12,7 @@
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use WebSocket\Message\Factory;
 
 class Base implements LoggerAwareInterface
 {
@@ -187,7 +188,7 @@ protected function sendFragment($final, $payload, $opcode, $masked): void
         ]);
     }
 
-    public function receive(): ?string
+    public function receive()
     {
         $filter = $this->options['filter'];
         if (!$this->isConnected()) {
@@ -239,7 +240,10 @@ public function receive(): ?string
         ]);
 
         $this->last_opcode = $payload_opcode;
-        return $payload;
+        $factory = new Factory();
+        return $this->options['return_obj']
+            ? $factory->create($payload_opcode, $payload)
+            : $payload;
     }
 
     protected function receiveFragment(): array

lib/Client.php

@@ -20,6 +20,7 @@ class Client extends Base
       'logger'        => null,
       'origin'        => null, // @deprecated
       'persistent'    => false,
+      'return_obj'    => false,
       'timeout'       => 5,
     ];
 

lib/Message/Binary.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace WebSocket\Message;
+
+class Binary extends Message
+{
+    protected $opcode = 'binary';
+}

lib/Message/Close.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace WebSocket\Message;
+
+class Close extends Message
+{
+    protected $opcode = 'close';
+}

lib/Message/Factory.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace WebSocket\Message;
+
+use WebSocket\BadOpcodeException;
+
+class Factory
+{
+    public function create(string $opcode, string $payload = ''): Message
+    {
+        switch ($opcode) {
+            case 'text':
+                return new Text($payload);
+            case 'binary':
+                return new Binary($payload);
+            case 'ping':
+                return new Ping($payload);
+            case 'pong':
+                return new Pong($payload);
+            case 'close':
+                return new Close($payload);
+        }
+        throw new BadOpcodeException("Invalid opcode '{$opcode}' provided");
+    }
+}

lib/Message/Message.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace WebSocket\Message;
+
+abstract class Message
+{
+    protected $opcode;
+    protected $payload;
+
+    public function __construct(string $payload = '')
+    {
+        $this->payload = $payload;
+    }
+
+    public function getOpcode(): string
+    {
+        return $this->opcode;
+    }
+
+    public function getLength(): int
+    {
+        return strlen($this->payload);
+    }
+
+    public function getContent(): string
+    {
+        return $this->payload;
+    }
+
+    public function setContent(string $payload = ''): void
+    {
+        $this->payload = $payload;
+    }
+
+    public function hasContent(): bool
+    {
+        return $this->payload != '';
+    }
+
+    public function __toString(): string
+    {
+        return get_class($this);
+    }
+}

lib/Message/Ping.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace WebSocket\Message;
+
+class Ping extends Message
+{
+    protected $opcode = 'ping';
+}

lib/Message/Pong.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace WebSocket\Message;
+
+class Pong extends Message
+{
+    protected $opcode = 'pong';
+}

lib/Message/Text.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace WebSocket\Message;
+
+class Text extends Message
+{
+    protected $opcode = 'text';
+}

lib/Server.php

@@ -17,6 +17,7 @@ class Server extends Base
       'fragment_size' => 4096,
       'logger'        => null,
       'port'          => 8000,
+      'return_obj'    => false,
       'timeout'       => null,
     ];
 

tests/ClientTest.php

@@ -380,6 +380,34 @@ public function testFrameFragmentation(): void
         $this->assertEquals('close', $client->getLastOpcode());
     }
 
+    public function testMessageFragmentation(): void
+    {
+        MockSocket::initialize('client.connect', $this);
+        $client = new Client(
+            'ws://localhost:8000/my/mock/path',
+            ['filter' => ['text', 'binary', 'pong', 'close'], 'return_obj' => true]
+        );
+        $client->send('Connect');
+        MockSocket::initialize('receive-fragmentation', $this);
+        $message = $client->receive();
+        $this->assertInstanceOf('WebSocket\Message\Message', $message);
+        $this->assertInstanceOf('WebSocket\Message\Pong', $message);
+        $this->assertEquals('Server ping', $message->getContent());
+        $this->assertEquals('pong', $message->getOpcode());
+        $message = $client->receive();
+        $this->assertInstanceOf('WebSocket\Message\Message', $message);
+        $this->assertInstanceOf('WebSocket\Message\Text', $message);
+        $this->assertEquals('Multi fragment test', $message->getContent());
+        $this->assertEquals('text', $message->getOpcode());
+        $this->assertTrue(MockSocket::isEmpty());
+        MockSocket::initialize('close-remote', $this);
+        $message = $client->receive();
+        $this->assertInstanceOf('WebSocket\Message\Message', $message);
+        $this->assertInstanceOf('WebSocket\Message\Close', $message);
+        $this->assertEquals('Closing', $message->getContent());
+        $this->assertEquals('close', $message->getOpcode());
+    }
+
     public function testConvenicanceMethods(): void
     {
         MockSocket::initialize('client.connect', $this);

tests/MessageTest.php

@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * Test case for Message subsection.
+ */
+
+declare(strict_types=1);
+
+namespace WebSocket;
+
+use PHPUnit\Framework\TestCase;
+use WebSocket\Message\Factory;
+use WebSocket\Message\Text;
+
+class MessageTest extends TestCase
+{
+
+    public function setUp(): void
+    {
+        error_reporting(-1);
+    }
+
+    public function testFactory(): void
+    {
+        $factory = new Factory();
+        $message = $factory->create('text', 'Some content');
+        $this->assertInstanceOf('WebSocket\Message\Text', $message);
+        $message = $factory->create('binary', 'Some content');
+        $this->assertInstanceOf('WebSocket\Message\Binary', $message);
+        $message = $factory->create('ping', 'Some content');
+        $this->assertInstanceOf('WebSocket\Message\Ping', $message);
+        $message = $factory->create('pong', 'Some content');
+        $this->assertInstanceOf('WebSocket\Message\Pong', $message);
+        $message = $factory->create('close', 'Some content');
+        $this->assertInstanceOf('WebSocket\Message\Close', $message);
+    }
+
+    public function testMessage()
+    {
+        $message = new Text('Some content');
+        $this->assertInstanceOf('WebSocket\Message\Message', $message);
+        $this->assertInstanceOf('WebSocket\Message\Text', $message);
+        $this->assertEquals('Some content', $message->getContent());
+        $this->assertEquals('text', $message->getOpcode());
+        $this->assertEquals(12, $message->getLength());
+        $this->assertTrue($message->hasContent());
+        $message->setContent('');
+        $this->assertEquals(0, $message->getLength());
+        $this->assertFalse($message->hasContent());
+        $this->assertEquals('WebSocket\Message\Text', "{$message}");
+    }
+
+    public function testBadOpcode()
+    {
+        $factory = new Factory();
+        $this->expectException('WebSocket\BadOpcodeException');
+        $this->expectExceptionMessage("Invalid opcode 'invalid' provided");
+        $message = $factory->create('invalid', 'Some content');
+    }
+}