diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md index eb29008..e4ecc1e 100644 --- a/docs/en/_sidebar.md +++ b/docs/en/_sidebar.md @@ -3,3 +3,6 @@ * MQTT Protocol Analysis * [Protocol API](en/protocol) + +* Upgrade Guide + * [1.2 Upgrade Guide](en/upgrade/1.2.md) \ No newline at end of file diff --git a/docs/en/client.md b/docs/en/client.md index b760464..2a6cd1f 100644 --- a/docs/en/client.md +++ b/docs/en/client.md @@ -5,38 +5,41 @@ Create a MQTT client instance ```php -Simps\MQTT\Client::__construct(array $config, array $swConfig = [], int $type = SWOOLE_SOCK_TCP, int $clientType = Client::COROUTINE_CLIENT_TYPE) +Simps\MQTT\Client::__construct(string $host, int $port, ?ClientConfig $config = null, int $clientType = Client::COROUTINE_CLIENT_TYPE) ``` -* `array $config` +* `string $host` -An array of client options, you can set the following options: +Broker's host + +* `int $port` + +Broker's port + +* `ClientConfig $config` + +ClientConfig object. + +Example. ```php $config = [ - 'host' => '127.0.0.1', - 'port' => 1883, - 'user_name' => '', - 'password' => '', - 'client_id' => '', - 'keep_alive' => 10, - 'protocol_name' => 'MQTT', // or MQIsdp - 'protocol_level' => 4, // or 3, 5 + 'userName' => '', // 用户名 + 'password' => '', // 密码 + 'clientId' => '', // 客户端id + 'keepAlive' => 10, // 默认0秒,设置成0代表禁用 + 'protocolName' => 'MQTT', // or MQIsdp + 'protocolLevel' => 4, // or 3, 5 'properties' => [], // optional in MQTT5 - 'reconnect_delay' => 3, + 'reconnectDelay' => 3, + 'swooleConfig' => [] ]; +$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. -* `array $swConfig` - -To set the configuration of `Swoole\Coroutine\Client`, please see Swoole document: [set()](https://www.swoole.co.uk/docs/modules/swoole-coroutine-client-set) - -* `int $type` - -Set `sockType`, such as: `SWOOLE_TCP`, `SWOOLE_TCP | SWOOLE_SSL` - * `int $clientType` Set the client type, use a Coroutine Client or a Sync Client, the default is Coroutine Client. diff --git a/docs/en/protocol.md b/docs/en/protocol.md index 28f3399..a6a56ab 100644 --- a/docs/en/protocol.md +++ b/docs/en/protocol.md @@ -5,17 +5,17 @@ Use `pack` and `unpack` to package and parse according to the MQTT protocol. ## MQTT 3.1.x ```php -Simps\MQTT\Protocol::pack(array $array) +Simps\MQTT\Protocol\V3::pack(array $array) -Simps\MQTT\Protocol::unpack(string $data) +Simps\MQTT\Protocol\V3::unpack(string $data) ``` ## MQTT 5.0 ```php -Simps\MQTT\ProtocolV5::pack(array $array) +Simps\MQTT\Protocol\V5::pack(array $array) -Simps\MQTT\ProtocolV5::unpack(string $data) +Simps\MQTT\Protocol\V5::unpack(string $data) ``` ## Constants @@ -23,12 +23,12 @@ Simps\MQTT\ProtocolV5::unpack(string $data) Constants for MQTT protocol levels and names ```php -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; // 3.1 -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1_1; // 3.1.1 -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0; // 5.0 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; // 3.1 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1_1; // 3.1.1 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0; // 5.0 -Simps\MQTT\ProtocolInterface::MQISDP_PROTOCOL_NAME; // MQIsdp -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_NAME; // MQTT +Simps\MQTT\Protocol\ProtocolInterface::MQISDP_PROTOCOL_NAME; // MQIsdp +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_NAME; // MQTT ``` ## ReasonCode diff --git a/docs/en/upgrade/1.2.md b/docs/en/upgrade/1.2.md new file mode 100644 index 0000000..77bcba0 --- /dev/null +++ b/docs/en/upgrade/1.2.md @@ -0,0 +1,93 @@ +# 1.2 Upgrade Guide + +Version 1.2 mainly changes the `__construct` parameters of the Client and the namespace of the Protocol. + +## Protocol + +A new layer of `Protocol` has been added, using `V3` and `V5` to differentiate between MQTT protocol levels. + +Also moved `Simps\MQTT\Types` to `Protocol` as well, changing it to `Simps\MQTT\Protocol\Types`. + +### 1.1 + +```php +Simps\MQTT\Protocol::pack(array $array) +Simps\MQTT\ProtocolV5::pack(array $array) +Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; + +Simps\MQTT\Types::CONNECT; +``` + +### 1.2 + +```php +Simps\MQTT\Protocol\V3::pack(array $array) +Simps\MQTT\Protocol\V5::pack(array $array) +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; + +Simps\MQTT\Protocol\Types::CONNECT; +``` + +## Client + +Client was previously passing array parameters directly, now it is an object. + +### 1.1 + +```php +use Simps\MQTT\Client; + +$config = [ + 'host' => '127.0.0.1', + 'port' => 1883, + 'user_name' => '', + 'password' => '', + 'client_id' => Client::genClientID(), + 'keep_alive' => 10, +]; +$swooleConfig = [ + 'open_mqtt_protocol' => true, + 'package_max_length' => 2 * 1024 * 1024, + 'connect_timeout' => 1.0, + 'write_timeout' => 3.0, + 'read_timeout' => 0.5, +]; +$client = new Client($config, $swooleConfig); +``` + +### 1.2 + +```php +use Simps\MQTT\Client; +use Simps\MQTT\Config\ClientConfig; + +$config = new ClientConfig(); +$config->setUserName('') + ->setPassword('') + ->setClientId(Client::genClientID()) + ->setKeepAlive(10); + +$swooleConfig = [ + 'open_mqtt_protocol' => true, + 'package_max_length' => 2 * 1024 * 1024, + 'connect_timeout' => 1.0, + 'write_timeout' => 3.0, + 'read_timeout' => 0.5, +]; +$config->setSwooleConfig($swooleConfig); +$client = new Client('127.0.0.1', 1883, $config); + +// You can also set it up like this +$config = new ClientConfig([ + 'userName' => '', + 'password' => '', + 'clientId' => '', + 'keepAlive' => 10, + 'protocolName' => 'MQTT', + 'protocolLevel' => 4, + 'properties' => [], + 'reconnectDelay' => 3, + 'swooleConfig' => [] +]); +$client = new Client('127.0.0.1', 1883, $config); +``` diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index e4502da..aca75e8 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -3,3 +3,6 @@ * MQTT 协议解析 * [Protocol API](zh-cn/protocol) + +* 版本升级指南 + * [1.2 升级指南](zh-cn/upgrade/1.2.md) \ No newline at end of file diff --git a/docs/zh-cn/client.md b/docs/zh-cn/client.md index 58c3965..3f27114 100644 --- a/docs/zh-cn/client.md +++ b/docs/zh-cn/client.md @@ -5,38 +5,41 @@ 创建一个MQTT客户端实例 ```php -Simps\MQTT\Client::__construct(array $config, array $swConfig = [], int $type = SWOOLE_SOCK_TCP, int $clientType = Client::COROUTINE_CLIENT_TYPE) +Simps\MQTT\Client::__construct(string $host, int $port, ?ClientConfig $config = null, int $clientType = Client::COROUTINE_CLIENT_TYPE) ``` -* 参数`array $config` +* 参数`string $host` -客户端选项数组,可以设置以下选项: +Broker 的 IP 地址 + +* 参数`int $port` + +Broker 的端口 + +* 参数`ClientConfig $config` + +客户端配置对象。 + +示例: ```php $config = [ - 'host' => '127.0.0.1', // MQTT服务端IP - 'port' => 1883, // MQTT服务端端口 - 'user_name' => '', // 用户名 + 'userName' => '', // 用户名 'password' => '', // 密码 - 'client_id' => '', // 客户端id - 'keep_alive' => 10, // 默认0秒,设置成0代表禁用 - 'protocol_name' => 'MQTT', // 协议名,默认为MQTT(3.1.1版本),也可为MQIsdp(3.1版本) - 'protocol_level' => 4, // 协议等级,MQTT3.1.1版本为4,5.0版本为5,MQIsdp为3 + 'clientId' => '', // 客户端id + 'keepAlive' => 10, // 默认0秒,设置成0代表禁用 + 'protocolName' => 'MQTT', // 协议名,默认为MQTT(3.1.1版本),也可为MQIsdp(3.1版本) + 'protocolLevel' => 4, // 协议等级,MQTT3.1.1版本为4,5.0版本为5,MQIsdp为3 'properties' => [], // MQTT5 中所需要的属性 - 'reconnect_delay' => 3, // 重连时的延迟时间 + 'reconnectDelay' => 3, // 重连时的延迟时间 + 'swooleConfig' => [] ]; +$configObj = new Simps\MQTT\Config\ClientConfig($config); +$client = new Simps\MQTT\Client('127.0.0.1', 1883, $configObj); ``` !> Client 会根据设置的`protocol_level`来使用对应的协议解析 -* 参数`array $swConfig` - -设置`Swoole\Coroutine\Client | Swoole\Client`的配置,请参考Swoole文档:[set()](https://wiki.swoole.com/#/coroutine_client/client?id=set) - -* 参数`int $type` - -设置`sockType`,如:`SWOOLE_TCP`、`SWOOLE_TCP | SWOOLE_SSL` - * 参数`int $clientType` 设置客户端类型,使用协程 Client 还是同步阻塞 Client。默认为协程 Client。 diff --git a/docs/zh-cn/protocol.md b/docs/zh-cn/protocol.md index 4f93b7a..1936b08 100644 --- a/docs/zh-cn/protocol.md +++ b/docs/zh-cn/protocol.md @@ -5,17 +5,17 @@ ## MQTT 3.1.x ```php -Simps\MQTT\Protocol::pack(array $array) +Simps\MQTT\Protocol\V3::pack(array $array) -Simps\MQTT\Protocol::unpack(string $data) +Simps\MQTT\Protocol\V3::unpack(string $data) ``` ## MQTT 5.0 ```php -Simps\MQTT\ProtocolV5::pack(array $array) +Simps\MQTT\Protocol\V5::pack(array $array) -Simps\MQTT\ProtocolV5::unpack(string $data) +Simps\MQTT\Protocol\V5::unpack(string $data) ``` ## Constants @@ -23,12 +23,12 @@ Simps\MQTT\ProtocolV5::unpack(string $data) MQTT 协议等级和名称的常量 ```php -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; // 3.1 -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1_1; // 3.1.1 -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0; // 5.0 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; // 3.1 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1_1; // 3.1.1 +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0; // 5.0 -Simps\MQTT\ProtocolInterface::MQISDP_PROTOCOL_NAME; // MQIsdp -Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_NAME; // MQTT +Simps\MQTT\Protocol\ProtocolInterface::MQISDP_PROTOCOL_NAME; // MQIsdp +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_NAME; // MQTT ``` ## ReasonCode diff --git a/docs/zh-cn/upgrade/1.2.md b/docs/zh-cn/upgrade/1.2.md new file mode 100644 index 0000000..e8bc887 --- /dev/null +++ b/docs/zh-cn/upgrade/1.2.md @@ -0,0 +1,93 @@ +# 1.2 升级指南 + +1.2 版本主要修改了 Client 的构造函数参数和 Protocol 的命名空间。 + +## Protocol + +新增一层`Protocol`,使用`V3`和`V5`来区分 MQTT 协议等级。 + +同时将`Simps\MQTT\Types`也移动到了`Protocol`下,修改为`Simps\MQTT\Protocol\Types`。 + +### 1.1 + +```php +Simps\MQTT\Protocol::pack(array $array) +Simps\MQTT\ProtocolV5::pack(array $array) +Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; + +Simps\MQTT\Types::CONNECT; +``` + +### 1.2 + +```php +Simps\MQTT\Protocol\V3::pack(array $array) +Simps\MQTT\Protocol\V5::pack(array $array) +Simps\MQTT\Protocol\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1; + +Simps\MQTT\Protocol\Types::CONNECT; +``` + +## Client + +Client 之前是直接传递数组参数的,现在改为对象的方式。 + +### 1.1 + +```php +use Simps\MQTT\Client; + +$config = [ + 'host' => '127.0.0.1', + 'port' => 1883, + 'user_name' => '', + 'password' => '', + 'client_id' => Client::genClientID(), + 'keep_alive' => 10, +]; +$swooleConfig = [ + 'open_mqtt_protocol' => true, + 'package_max_length' => 2 * 1024 * 1024, + 'connect_timeout' => 1.0, + 'write_timeout' => 3.0, + 'read_timeout' => 0.5, +]; +$client = new Client($config, $swooleConfig); +``` + +### 1.2 + +```php +use Simps\MQTT\Client; +use Simps\MQTT\Config\ClientConfig; + +$config = new ClientConfig(); +$config->setUserName('') + ->setPassword('') + ->setClientId(Client::genClientID()) + ->setKeepAlive(10); + +$swooleConfig = [ + 'open_mqtt_protocol' => true, + 'package_max_length' => 2 * 1024 * 1024, + 'connect_timeout' => 1.0, + 'write_timeout' => 3.0, + 'read_timeout' => 0.5, +]; +$config->setSwooleConfig($swooleConfig); +$client = new Client('127.0.0.1', 1883, $config); + +// 也可以这样设置 +$config = new ClientConfig([ + 'userName' => '', + 'password' => '', + 'clientId' => '', + 'keepAlive' => 10, + 'protocolName' => 'MQTT', + 'protocolLevel' => 4, + 'properties' => [], + 'reconnectDelay' => 3, + 'swooleConfig' => [] +]); +$client = new Client('127.0.0.1', 1883, $config); +```