Support mqtt over websocket (#109)

simps · Jan 18, 2025 · d1a01fb · d1a01fb
1 parent 5cc7ef3
commit d1a01fb
Show file tree

Hide file tree

Showing 24 changed files with 1,429 additions and 353 deletions.
diff --git a/.github/workflows/phpstan.yml b/.github/workflows/phpstan.yml
@@ -30,7 +30,7 @@ jobs:
 
       - name: Setup Dependencies
         env:
-          COMPOSER_ROOT_VERSION: 1.x-dev
+          COMPOSER_ROOT_VERSION: 2.x-dev
         run:
           composer install -o
 

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -80,7 +80,7 @@ jobs:
 
       - name: Setup Dependencies
         env:
-          COMPOSER_ROOT_VERSION: 1.x-dev
+          COMPOSER_ROOT_VERSION: 2.x-dev
         run: composer install -o
 
       - name: Coding Standards Check

diff --git a/README-CN.md b/README-CN.md
@@ -6,6 +6,8 @@
 
 支持 MQTT 协议 `3.1`、`3.1.1` 和 `5.0` 版本，支持`QoS 0`、`QoS 1`、`QoS 2`。
 
+支持 MQTT over WebSocket。
+
 > 首个支持 MQTT `5.0` 协议的 PHP library。
 
 [![License](https://poser.pugx.org/simps/mqtt/license)](LICENSE)

diff --git a/README.md b/README.md
@@ -8,6 +8,8 @@ Support for MQTT protocol versions `3.1`, `3.1.1` and `5.0`.
 
 Support for `QoS 0`, `QoS 1`, `QoS 2`.
 
+Support for MQTT over WebSocket.
+
 > The first PHP library to support the MQTT `5.0` protocol.
 
 [![License](https://poser.pugx.org/simps/mqtt/license)](LICENSE)

diff --git a/composer.json b/composer.json
@@ -55,7 +55,7 @@
   },
   "extra": {
     "branch-alias": {
-      "dev-master": "1.x-dev"
+      "dev-master": "2.x-dev"
     }
   }
 }
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -6,6 +6,7 @@
 
 - Support for QoS 0, 1, 2
 - Support for MQTT 3.1, 3.1.1, 5.0
+- Support for MQTT over WebSocket
 - The first PHP library to support the MQTT 5.0 protocol
 
 [Gitee](https://gitee.com/phpmqtt/mqtt)

diff --git a/docs/en/README.md b/docs/en/README.md
@@ -6,6 +6,8 @@ Support for MQTT protocol versions `3.1`, `3.1.1` and `5.0`.
 
 Support for `QoS 0`, `QoS 1`, `QoS 2`.
 
+Support for MQTT over WebSocket.
+
 ## Requirements
 
 * PHP >= `7.1`

diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md
@@ -1,11 +1,15 @@
-* MQTT Coroutine Client
-  * [Client API](en/client)
+- MQTT Coroutine Client
+  - [Client API](en/client)
+  - [WebSocket Client API](en/websocket)
 
-* MQTT Protocol Analysis
-  * [Protocol API](en/protocol)
+- MQTT Protocol Analysis
+  - [Protocol API](en/protocol)
 
-* MQTT Message
-  * [Message API](en/message)
+- MQTT Message
+  - [Message API](en/message)
 
-* Upgrade Guide
-  * [1.2 Upgrade Guide](en/upgrade/1.2.md)
+- Upgrade Guide
+  - [1.2 Upgrade Guide](en/upgrade/1.2)
+
+- Tools
+  - [Debug Tools](en/debug)
diff --git a/docs/en/client.md b/docs/en/client.md
@@ -8,15 +8,15 @@ Create a MQTT client instance
 Simps\MQTT\Client::__construct(string $host, int $port, ClientConfig $config, int $clientType = Client::COROUTINE_CLIENT_TYPE)
 ```
 
-* `string $host`
+- `string $host`
 
 Broker's host
 
-* `int $port`
+- `int $port`
 
 Broker's port
 
-* `ClientConfig $config`
+- `ClientConfig $config`
 
 ClientConfig object.
 
@@ -39,9 +39,9 @@ $configObj = new Simps\MQTT\Config\ClientConfig($config);
 $client = new Simps\MQTT\Client('127.0.0.1', 1883, $configObj);
 ```
 
-!> The Client will use the corresponding protocol resolution according to the `protocol_level` set.
+!> The Client will use the corresponding protocol resolution according to the `protocolLevel` set.
 
-* `int $clientType`
+- `int $clientType`
 
 Set the client type, use a Coroutine Client or a Sync Client, the default is Coroutine Client.
 
@@ -55,13 +55,13 @@ Connect Broker
 Simps\MQTT\Client->connect(bool $clean = true, array $will = [])
 ```
 
-* `bool $clean`
+- `bool $clean`
 
 Clean session. default is `true`.
 
 For a detailed description, please see the corresponding protocol document: `Clean Session`.
 
-* `array $will`
+- `array $will`
 
 When a client is disconnected, Broker will automatically send a will message to other clients
 
@@ -91,13 +91,13 @@ Subscribe to one topic or multiple topics
 Simps\MQTT\Client->subscribe(array $topics, array $properties = [])
 ```
 
-* `array $topics`
+- `array $topics`
 
 ```php
 // MQTT 3.x
 $topics = [
     // topic => Qos
-    'topic1' => 0, 
+    'topic1' => 0,
     'topic2' => 1,
 ];
 
@@ -109,17 +109,17 @@ $topics = [
         'no_local' => true,
         'retain_as_published' => true,
         'retain_handling' => 2,
-    ], 
+    ],
     'topic2' => [
         'qos' => 2,
         'no_local' => false,
         'retain_as_published' => true,
         'retain_handling' => 1,
-    ], 
+    ],
 ];
 ```
 
-* `array $properties`
+- `array $properties`
 
 Optional in MQTT5
 
@@ -131,13 +131,13 @@ Unsubscribe from a topic or multiple topics
 Simps\MQTT\Client->unSubscribe(array $topics, array $properties = [])
 ```
 
-* `array $topics`
+- `array $topics`
 
 ```php
 $topics = ['topic1', 'topic2'];
 ```
 
-* `array $properties`
+- `array $properties`
 
 Optional in MQTT5
 
@@ -157,14 +157,6 @@ New AUTH type added in MQTT5. Authentication exchange.
 Simps\MQTT\Client->auth(int $code = ReasonCode::SUCCESS, array $properties = [])
 ```
 
-## recv()
-
-Receive messages
-
-```php
-Simps\MQTT\Client->recv(): bool|arary|string
-```
-
 ## send()
 
 Send messages
@@ -173,14 +165,22 @@ Send messages
 Simps\MQTT\Client->send(array $data, $response = true)
 ```
 
-* `array $data`
+- `array $data`
 
 `$data` is the data to be sent and must contain information such as `type`
 
-* `bool $response`
+- `bool $response`
 
 Are acknowledgements required. If `true`, `recv()` is called once
 
+## recv()
+
+Receive messages
+
+```php
+Simps\MQTT\Client->recv(): bool|arary|string
+```
+
 ## ping()
 
 Send a heartbeat

diff --git a/docs/en/debug.md b/docs/en/debug.md
@@ -0,0 +1,52 @@
+# Debug Tools
+
+The tool provides 5 methods for debugging binary data, essentially functioning as a binary data viewer.
+
+It primarily converts binary data into ASCII or hexadecimal formats for viewing, useful for debugging TCP, WebSocket, UDP, and other protocols.
+
+```php
+public function hexDump(): string // Display in hexadecimal
+public function hexDumpAscii(): string // Display in both hexadecimal and corresponding ASCII characters
+public function printableText(): string // Printable characters
+public function hexStream(): string // Hexadecimal stream
+public function ascii(): string // Display in ASCII characters
+```
+
+You can call these methods statically or instantiate `Simps\MQTT\Tools\Debug` or `Simps\MQTT\Tools\Common`/`Simps\MQTT\Tools\UnPackTool`:
+
+- Instantiation
+
+```php
+use Simps\MQTT\Tools\Debug;
+
+$debug = new Debug('0:simps-mqtt/user001/update{
+  "msg": "hello, mqtt"
+}');
+
+//$debug = (new Debug())->setEncode('0:simps-mqtt/user001/update{
+//  "msg": "hello, mqtt"
+//}');
+
+echo $debug->hexDump(), PHP_EOL;
+echo $debug->hexDumpAscii(), PHP_EOL;
+echo $debug->printableText(), PHP_EOL;
+echo $debug->hexStream(), PHP_EOL;
+echo $debug->ascii();
+```
+
+- Static call
+
+```php
+use Simps\MQTT\Tools\UnPackTool;
+
+echo UnPackTool::hexDumpAscii('0:simps-mqtt/user001/update{
+  "msg": "hello, mqtt"
+}');
+```
+
+```text
+00000000    30 3a 73 69 6d 70 73 2d 6d 71 74 74 2f 75 73 65    0:simps-mqtt/use
+00000010    72 30 30 31 2f 75 70 64 61 74 65 7b 0a 20 20 22    r001/update{.  "
+00000020    6d 73 67 22 3a 20 22 68 65 6c 6c 6f 2c 20 6d 71    msg": "hello, mq
+00000030    74 74 22 0a 7d                                     tt".}
+```