# Client API
## __construct()
創建一個MQTT客戶端實例
```php
Simps\MQTT\Client::__construct(string $host, int $port, ClientConfig $config, int $clientType = Client::COROUTINE_CLIENT_TYPE)
```
* 參數`string $host`
Broker 的 IP 地址
* 參數`int $port`
Broker 的端口
* 參數`ClientConfig $config`
客戶端配置對象。
示例：
```php
$config = [
'userName' => '', // 用戶名
'password' => '', // 密碼
'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 中所需要的屬性
'delay' => 3000, // 重連時的延遲時間 (毫秒)
'maxAttempts' => 5, // 最大重連次數。默認-1，表示不限制
'swooleConfig' => []
];
$configObj = new Simps\MQTT\Config\ClientConfig($config);
$client = new Simps\MQTT\Client('127.0.0.1', 1883, $configObj);
```
!> Client 會根據設置的`protocol_level`來使用對應的協議解析
* 參數`int $clientType`
設置客戶端類型，使用協程 Client 還是同步阻塞 Client。默認為協程 Client。
同步阻塞 Client 適用于 Fpm|Apache 環境，主要用于`publish`消息，設置為`Client::SYNC_CLIENT_TYPE`。
## connect()
連接Broker
```php
Simps\MQTT\Client->connect(bool $clean = true, array $will = [])
```
* 參數`bool $clean`
清理會話，默認為`true`
具體描述請查看對應協議文檔：`清理會話 Clean Session`
* 參數`array $will`
遺囑消息，當客戶端斷線后Broker會自動發送遺囑消息給其它客戶端
需要設置的內容如下
```php
$will = [
'topic' => '', // 主題
'qos' => 1, // QoS等級
'retain' => 0, // retain標記
'message' => '', // 遺囑消息內容
'properties' => [], // MQTT5 中需要，可選
];
```
## publish()
向某個主題發布一條消息
```php
Simps\MQTT\Client->publish($topic, $message, $qos = 0, $dup = 0, $retain = 0, array $properties = [])
```
* 參數`$topic` 主題
* 參數`$message` 內容
* 參數`$qos` QoS等級，默認0
* 參數`$dup` 重發標志，默認0
* 參數`$retain` retain標記，默認0
* 參數`$properties` 屬性，MQTT5 中需要，可選
## subscribe()
訂閱一個主題或者多個主題
```php
Simps\MQTT\Client->subscribe(array $topics, array $properties = [])
```
* 參數`array $topics`
`$topics`的`key`是主題，值為`QoS`的數組，例如
```php
// MQTT 3.x
$topics = [
// 主題 => Qos
'topic1' => 0,
'topic2' => 1,
];
// MQTT 5.0
$topics = [
// 主題 => 選項
'topic1' => [
'qos' => 1,
'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`
屬性，MQTT5 中需要，可選
## unSubscribe()
取消訂閱一個主題或者多個主題
```php
Simps\MQTT\Client->unSubscribe(array $topics, array $properties = [])
```
* 參數`array $topics`
```php
$topics = ['topic1', 'topic2'];
```
* 參數`array $properties`
屬性，MQTT5 中需要，可選
## close()
正常斷開與Broker的連接，`DISCONNECT(14)`報文會被發送到Broker
```php
Simps\MQTT\Client->close(int $code = ReasonCode::NORMAL_DISCONNECTION, array $properties = [])
```
* 參數`int $code`
響應碼，MQTT5 中需要，MQTT3直接調用即可
* 參數`array $properties`
屬性，MQTT5中需要
## auth()
MQTT5 中新增的認證交換機制。
```php
Simps\MQTT\Client->auth(int $code = ReasonCode::SUCCESS, array $properties = [])
```
## 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(string $prefix = 'Simps_')
```
