From 8c61d2801fc57d4a1bd3c577c59e3691a1caf1a6 Mon Sep 17 00:00:00 2001 From: sy-records <52o@qq52o.cn> Date: Mon, 14 Dec 2020 16:13:07 +0800 Subject: [PATCH] Add docs --- README-CN.md | 2 +- README.md | 2 +- docs/.nojekyll | 0 docs/_navbar.md | 3 + docs/en/README.md | 171 ++++++++++++++++++++++++++++++++++++++++ docs/favicon.ico | Bin 0 -> 16958 bytes docs/index.html | 37 +++++++++ docs/zh-cn/README.md | 183 +++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 396 insertions(+), 2 deletions(-) create mode 100644 docs/.nojekyll create mode 100644 docs/_navbar.md create mode 100644 docs/en/README.md create mode 100644 docs/favicon.ico create mode 100644 docs/index.html create mode 100644 docs/zh-cn/README.md diff --git a/README-CN.md b/README-CN.md index 10600b8..63f0d0e 100644 --- a/README-CN.md +++ b/README-CN.md @@ -17,7 +17,7 @@ composer require simps/mqtt ## 示例 -参考 [examples](./examples) 目录 +参考 [examples](https://github.com/simps/mqtt/tree/master/examples) 目录 ## Client API diff --git a/README.md b/README.md index 85b24be..42bb8c5 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ composer require simps/mqtt ## Examples -see [examples](./examples) +see [examples](https://github.com/simps/mqtt/tree/master/examples) ## Client API diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/_navbar.md b/docs/_navbar.md new file mode 100644 index 0000000..43a9801 --- /dev/null +++ b/docs/_navbar.md @@ -0,0 +1,3 @@ +- Translations + - [:cn: 中文](/zh-cn/) + - [:uk: English](/en/) \ No newline at end of file diff --git a/docs/en/README.md b/docs/en/README.md new file mode 100644 index 0000000..a0c8975 --- /dev/null +++ b/docs/en/README.md @@ -0,0 +1,171 @@ +# MQTT Coroutine Client + +MQTT Protocol Analysis and Coroutine Client for PHP. + +[![Latest Stable Version](https://poser.pugx.org/simps/mqtt/v)](//packagist.org/packages/simps/mqtt) +[![Total Downloads](https://poser.pugx.org/simps/mqtt/downloads)](//packagist.org/packages/simps/mqtt) +[![Latest Unstable Version](https://poser.pugx.org/simps/mqtt/v/unstable)](//packagist.org/packages/simps/mqtt) +[![License](https://poser.pugx.org/simps/mqtt/license)](https://github.com/simps/mqtt/blob/master/LICENSE) + +## Install + +```bash +composer require simps/mqtt +``` + +## Examples + +see [examples](https://github.com/simps/mqtt/tree/master/examples) + +## Client API + +### __construct() + +Create a MQTT client instance + +```php +Simps\MQTT\Client::__construct(array $config, array $swConfig = [], int $type = SWOOLE_SOCK_TCP) +``` + +* `array $config` + +An array of client options, you can set the following options: + +```php +$config = [ + 'host' => '127.0.0.1', + 'port' => 1883, + 'time_out' => 5, + 'user_name' => '', + 'password' => '', + 'client_id' => '', + 'keep_alive' => 10, + 'protocol_name' => 'MQTT', // or MQIsdp + 'protocol_level' => 4, // or 3 +]; +``` + +* `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) + +### connect() + +Connect Broker + +```php +Simps\MQTT\Client->connect(bool $clean = true, array $will = []) +``` + +* `bool $clean` + +Clean session. default is `true`. see [Clean Session](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/errata01/os/mqtt-v3.1.1-errata01-os-complete.html#_Toc442180843) + +* `array $will` + +When a client is disconnected, Broker will automatically send a will message to other clients + +```php +$will = [ + 'topic' => '', + 'qos' => 1, + 'retain' => 0, + 'content' => '', +]; +``` + +### publish() + +push a message to a topic + +```php +Simps\MQTT\Client->publish($topic, $content, $qos = 0, $dup = 0, $retain = 0) +``` + +### subscribe() + +Subscribe to one topic or multiple topics + +```php +Simps\MQTT\Client->subscribe(array $topics) +``` + +* `array $topics` + +```php +$topics = [ + // topic => Qos + 'topic1' => 0, + 'topic2' => 1, +]; +``` + +### unSubscribe() + +Unsubscribe from a topic or multiple topics + +```php +Simps\MQTT\Client->unSubscribe(array $topics) +``` + +* `array $topics` + +```php +$topics = ['topic1', 'topic2']; +``` + +### close() + +Disconnect from Broker connect. The `DISCONNECT(14)` message is send to Broker + +```php +Simps\MQTT\Client->close() +``` + +### recv() + +Receive messages + +```php +Simps\MQTT\Client->recv(): bool|arary|string +``` + +### send() + +Send messages + +```php +Simps\MQTT\Client->send(array $data, $response = true) +``` + +* `array $data` + +`$data` is the data to be sent and must contain information such as `type` + +* `bool $response` + +Are acknowledgements required. If `true`, `recv()` is called once + +### ping() + +Send a heartbeat + +```php +Simps\MQTT\Client->ping() +``` + +### buildMessageId() + +Generate MessageId + +```php +Simps\MQTT\Client->buildMessageId() +``` + +### genClientId() + +Generate ClientId + +```php +Simps\MQTT\Client->genClientID() +``` diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..c094215cd57c627211f32cf94dd96e253d17530f GIT binary patch literal 16958 zcmeI4dr(wW9LIkvD32^e5z|l{W&%?o*J>uG98hPP9A+GCrv52svY0GtD5nQH)QEqS z zCu+c+APO`Co&(oF67Y%hKzbSwR{{2CtY9Yar8zJezG@C|4Gw^?!B&G~>xh8g@eB&8 z`J94k*Hds^HU*v7L;)wakO4R?>?lb?RCC}a)|aa9oDTA$hM!gu9sP`kRIa9&sx`E@ zdM#~(|BvuD!M_6jrW2d#ho84nX2VzXV&m5ob>$^x-eyFW@iCJ3}wE;D7NKEqN1#B|q-exx%OB z?pYYd<2(Uafbws|`h&nLhF`irgjfIsW6qx}s@Dzc%io6i-+}qx=`jA%|50Hrinq2O zNKDwh@L~R2fTMpIw)q{wZ2E3E!QWus6*i(ZFKSj>{NK0xg6YB^Wg2eNt zg>SZ(C8b!4Uw`g=MQZ3Tr75ls8_+g*^0+fAm9t}PDT)&{F0TK_GwCqgL)d>XFVcMs zVx6P6~x_{IhT`r2mP3B78d>ox9gdjNY=TEKHH8K_-661jii2X=ygo&P=G8wEcTHEa(TbsPN! z{P)*o(FjDR1;_C3Ga=wD&tG&mI%c37I0x_{aMQnMKl8q5(fDn6S7XkojFzI< zajhjro=bdf3k2*u1uO#PpcAM*{=j-17-(Im{x}B^4=w|hpPSLB?T2T?8#wk1Fo9BV z5LAKR!7c9-*ydv@0oTVVpMh@R9Aqws5#98@ILZ&IODH12G5qJ%isjJf-W@FXtk87V!eOS95^p*SoSWr#w8_Aafdm$bSQI{VsIp zb>Xq+zpr^xwb#BmFTnS(72s~y;7|M}Klf^Lt=A+x{DsUf81Wsz_piHgE?mX$qym1{ z@~~mw-E)qB&xP55uZgbi;qKPu5{~C{o}Y>O?%YfE;9Mo)h>Jl5xB}eu=KCDiZa(05 zY%ekEUmBdZgrC>ufKLHG-T$ zm+y^h;$ANC^2cSgsTgT*x7`*+ zh`n6|+!p=h_6jXtjI7XNx}S-ojmW~Wi|FO$h#f=|IbMW4M++i?Fws&Og~7hfpF*T- zTh0+jb@2Cyo%Xo=FB#kHF@6Qdbo>Vkw?!>q6VWXZd1ziLB0tR+`DzjQNAmBW!+0&4 Ov~(e&^tINz{P7QAu|3ED literal 0 HcmV?d00001 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..a1e7e0b --- /dev/null +++ b/docs/index.html @@ -0,0 +1,37 @@ + + + + + Simps MQTT 文档 + + + + + + + + +
+ + + + + diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 0000000..66f876b --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,183 @@ +# MQTT 协程客户端 + +适用于 PHP 的 MQTT 协议解析和协程客户端。 + +[![Latest Stable Version](https://poser.pugx.org/simps/mqtt/v)](//packagist.org/packages/simps/mqtt) +[![Total Downloads](https://poser.pugx.org/simps/mqtt/downloads)](//packagist.org/packages/simps/mqtt) +[![Latest Unstable Version](https://poser.pugx.org/simps/mqtt/v/unstable)](//packagist.org/packages/simps/mqtt) +[![License](https://poser.pugx.org/simps/mqtt/license)](https://github.com/simps/mqtt/blob/master/LICENSE) + +## 安装 + +```bash +composer require simps/mqtt +``` + +## 示例 + +参考 [examples](./examples) 目录 + +## Client API + +### __construct() + +创建一个MQTT客户端实例 + +```php +Simps\MQTT\Client::__construct(array $config, array $swConfig = [], int $type = SWOOLE_SOCK_TCP) +``` + +* 参数`array $config` + +客户端选项数组，可以设置以下选项： + +```php +$config = [ + 'host' => '127.0.0.1', // MQTT服务端IP + 'port' => 1883, // MQTT服务端端口 + 'time_out' => 5, // 连接MQTT服务端超时时间，默认0.5秒 + 'user_name' => '', // 用户名 + 'password' => '', // 密码 + 'client_id' => '', // 客户端id + 'keep_alive' => 10, // 默认0秒，设置成0代表禁用 + 'protocol_name' => 'MQTT', // 协议名，默认为MQTT(3.1.1版本)，也可为MQIsdp(3.1版本) + 'protocol_level' => 4, // 协议等级，MQTT为4，MQIsdp为3 +]; +``` + +* 参数`array $swConfig` + +用于设置`Swoole\Coroutine\Client`的配置，请参考Swoole文档：[set()](https://wiki.swoole.com/#/coroutine_client/client?id=set) + +### connect() + +连接Broker + +```php +Simps\MQTT\Client->connect(bool $clean = true, array $will = []) +``` + +* 参数`bool $clean` + +清理会话，默认为`true` + +具体描述请参考[清理会话 Clean Session](https://mcxiaoke.gitbook.io/mqtt/03-controlpackets/0301-connect#qing-li-hui-hua-clean-session) + +* 参数`array $will` + +遗嘱消息，当客户端断线后Broker会自动发送遗嘱消息给其它客户端 + +需要设置的内容如下 + +```php +$will = [ + 'topic' => '', // 主题 + 'qos' => 1, // QoS等级 + 'retain' => 0, // retain标记 + 'content' => '', // content +]; +``` + +### publish() + +向某个主题发布一条消息 + +```php +Simps\MQTT\Client->publish($topic, $content, $qos = 0, $dup = 0, $retain = 0) +``` + +* 参数`$topic` 主题 +* 参数`$content` 内容 +* 参数`$qos` QoS等级，默认0 +* 参数`$dup` 重发标志，默认0 +* 参数`$retain` retain标记，默认0 + +### subscribe() + +订阅一个主题或者多个主题 + +```php +Simps\MQTT\Client->subscribe(array $topics) +``` + +* 参数`array $topics` + +`$topics`的`key`是主题，值为`QoS`的数组，例如 + +```php +$topics = [ + // 主题 => Qos + 'topic1' => 0, + 'topic2' => 1, +]; +``` + +### unSubscribe() + +取消订阅一个主题或者多个主题 + +```php +Simps\MQTT\Client->unSubscribe(array $topics) +``` + +* 参数`array $topics` + +```php +$topics = ['topic1', 'topic2']; +``` + +### close() + +正常断开与Broker的连接，`DISCONNECT(14)`报文会被发送到Broker + +```php +Simps\MQTT\Client->close() +``` + +### recv() + +接收消息 + +```php +Simps\MQTT\Client->recv(): bool|arary|string +``` + +### send() + +发送消息 + +```php +Simps\MQTT\Client->send(array $data, $response = true) +``` + +* 参数`array $data` + +`$data`是需要发送的数据，必须包含`type`等信息 + +* 参数`bool $response` + +是否需要回执。如果为`true`，会调用一次`recv()` + +### ping() + +发送心跳包 + +```php +Simps\MQTT\Client->ping() +``` + +### buildMessageId() + +生成MessageId + +```php +Simps\MQTT\Client->buildMessageId() +``` + +### genClientId() + +生成ClientId + +```php +Simps\MQTT\Client->genClientID() +```