MQTT Protocol Analysis & Coroutine Client

https://github.com/simps/mqtt
Admin
A PHP library that provides MQTT protocol analysis and a coroutine client, supporting MQTT versions...
Tokens:18,740
Snippets:86
Trust Score:5.7
License:Apache-2.0
Update:11 months ago
Show doc for...
Tokens:
Raw
### Simps MQTT Client Initialization (v1.1 vs v1.2)

Source: https://github.com/simps/mqtt/blob/master/docs/en/upgrade/1.2.md

Demonstrates the evolution of the Simps/MQTT Client initialization process from version 1.1 to 1.2. Version 1.1 used an array for configuration, while 1.2 adopts an object-oriented approach using `ClientConfig` for more structured parameter management.

```php
<?php
use Simps\MQTT\Client;

// v1.1 Client configuration
$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);
?>
```

```php
<?php
use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;

// v1.2 Client configuration using ClientConfig object
$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);

// Alternative v1.2 initialization with constructor arguments
$config = new ClientConfig([
    'userName' => '',
    'password' => '',
    'clientId' => '',
    'keepAlive' => 10,
    'protocolName' => 'MQTT',
    'protocolLevel' => 4,
    'properties' => [],
    'delay' => 3000, // 3s
    'swooleConfig' => []
]);
$client = new Client('127.0.0.1', 1883, $config);
?>
```

--------------------------------

### Instantiate and Configure MQTT Client in PHP

Source: https://context7.com/simps/mqtt/llms.txt

Demonstrates how to create an MQTT client instance using `Simps\MQTT\Client` and `Simps\MQTT\Config\ClientConfig`. It covers essential configuration options like Client ID, authentication, keep-alive interval, protocol level, reconnection strategy, and Swoole-specific settings. The example includes basic error handling for connection failures.

```php
<?php
require 'vendor/autoload.php';

use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;

// Create configuration
$config = new ClientConfig();
$config->setClientId('my_iot_device_001')
    ->setUserName('mqtt_user')
    ->setPassword('secure_password')
    ->setKeepAlive(60)
    ->setProtocolLevel(4) // 3 = MQTT 3.1, 4 = MQTT 3.1.1, 5 = MQTT 5.0
    ->setDelay(3000) // Reconnection delay in milliseconds
    ->setMaxAttempts(5) // Maximum reconnection attempts (0 = infinite)
    ->setSwooleConfig([
        'open_mqtt_protocol' => true,
        'package_max_length' => 2 * 1024 * 1024,
        'connect_timeout' => 5.0,
        'write_timeout' => 5.0,
        'read_timeout' => 5.0,
    ]);

// Create client instance
try {
    $client = new Client('127.0.0.1', 1883, $config);
    echo "Client created successfully\n";
} catch (Simps\MQTT\Exception\ConnectException $e) {
    echo "Connection failed: " . $e->getMessage() . "\n";
    exit(1);
}

```

--------------------------------

### Send MQTT SubAck Message (PHP)

Source: https://github.com/simps/mqtt/blob/master/docs/en/message.md

Examples of sending a formatted MQTT SubAck message using server and client instances. The server example shows direct sending, while the client example illustrates how to send with an option to retrieve the message as an array.

```php
$server->send($fd, $ack->getContents());
$server->send($fd, (string) $ack);
```

```php
// Add param to get an array
$client->send($ack->getContents(true), false);
```

--------------------------------

### Example Hexadecimal ASCII Dump Output

Source: https://github.com/simps/mqtt/blob/master/docs/en/debug.md

An example of the output generated by a hexadecimal ASCII dump tool for a specific binary string. It shows the byte offset, hexadecimal representation, and corresponding ASCII characters for each line of data.

```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".}
```

--------------------------------

### Establish MQTT Connection with Last Will in PHP

Source: https://context7.com/simps/mqtt/llms.txt

Shows how to connect to an MQTT broker using `Simps\MQTT\Client` within a Swoole coroutine. This example demonstrates setting a client ID, keep-alive interval, and maximum reconnection attempts. It also includes the configuration and transmission of a Last Will Testament message, specifying its topic, QoS, retain flag, and payload.

```php
<?php
use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;
use Swoole\Coroutine;

Coroutine\run(function () {
    $config = new ClientConfig();
    $config->setClientId(Client::genClientID('sensor_'))
        ->setKeepAlive(60)
        ->setMaxAttempts(3);

    $client = new Client('broker.emqx.io', 1883, $config);

    // Define Last Will Testament message
    $will = [
        'topic' => 'devices/sensor_001/status',
        'qos' => 1,
        'retain' => 1,
        'message' => json_encode(['status' => 'offline', 'timestamp' => time()]),
    ];

    try {
        // Connect with clean session and will message
        $response = $client->connect(true, $will);

        if ($response && isset($response['code']) && $response['code'] === 0) {
            echo "Connected successfully to broker\n";
            echo "Session present: " . ($response['session_present'] ?? 0) . "\n";
        } else {
            echo "Connection failed with code: " . ($response['code'] ?? 'unknown') . "\n";
        }
    } catch (\Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
    }
});

```

--------------------------------

### MQTT Protocol Packing and Constants (v1.1 vs v1.2)

Source: https://github.com/simps/mqtt/blob/master/docs/en/upgrade/1.2.md

Compares the method signatures and constant locations for packing MQTT data and accessing protocol levels and types between Simps/MQTT versions 1.1 and 1.2. Version 1.2 introduces a new Protocol namespace and separates V3 and V5 implementations.

```php
<?php
// Simps/MQTT v1.1 Protocol examples
Simps\MQTT\Protocol::pack(array $array);
Simps\MQTT\ProtocolV5::pack(array $array);
Simps\MQTT\ProtocolInterface::MQTT_PROTOCOL_LEVEL_3_1;

Simps\MQTT\Types::CONNECT;
?>
```

```php
<?php
// Simps/MQTT v1.2 Protocol examples
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;
?>
```

--------------------------------

### Publish MQTT Messages with QoS in PHP

Source: https://context7.com/simps/mqtt/llms.txt

Illustrates how to publish messages to MQTT topics with different Quality of Service (QoS) levels using `Simps\MQTT\Client`. The example covers QoS 0 (at most once), QoS 1 (at least once), and QoS 2 (exactly once) delivery. It also shows how to set the DUP and Retain flags for published messages, within a Swoole coroutine context.

```php
<?php
use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;
use Swoole\Coroutine;

Coroutine\run(function () {
    $config = new ClientConfig();
    $config->setClientId('publisher_001')
        ->setKeepAlive(60);

    $client = new Client('127.0.0.1', 1883, $config);
    $client->connect();

    // QoS 0: At most once delivery (fire and forget)
    $result = $client->publish(
        'sensors/temperature',
        json_encode(['value' => 22.5, 'unit' => 'celsius']),
        0, // QoS
        0, // DUP flag
        0  // Retain flag
    );
    echo "QoS 0 publish: " . ($result ? "success" : "failed") . "\n";

    // QoS 1: At least once delivery (acknowledged)
    $result = $client->publish(
        'sensors/humidity',
        json_encode(['value' => 65, 'unit' => 'percent']),
        1, // QoS
        0, // DUP flag
        1  // Retain flag (broker stores last message)
    );
    var_dump($result); // Returns PUBACK response

    // QoS 2: Exactly once delivery (assured)
    $result = $client->publish(
        'sensors/pressure',
        json_encode(['value' => 1013.25, 'unit' => 'hPa']),
        2, // QoS
        0, // DUP flag
        0  // Retain flag
    );
    var_dump($result); // Returns PUBREC/PUBREL/PUBCOMP flow

    Coroutine::sleep(1);
    $client->close();
});

```

--------------------------------

### Publish MQTT 5.0 Messages with Properties (PHP)

Source: https://context7.com/simps/mqtt/llms.txt

Publishes messages using MQTT 5.0, leveraging features like session expiry, receive maximum, topic aliases, and custom user properties. This example requires the Simps MQTT client and Swoole coroutines. It demonstrates both initial connection and subsequent publishes using topic aliases for efficiency.

```php
<?php
use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;
use Swoole\Coroutine;

Coroutine\run(function () {
    // Configure for MQTT 5.0
    $config = new ClientConfig();
    $config->setClientId(Client::genClientID())
        ->setKeepAlive(60)
        ->setProtocolLevel(5) // MQTT 5.0
        ->setProperties([
            'session_expiry_interval' => 300,
            'receive_maximum' => 65535,
            'maximum_packet_size' => 1048576,
            'topic_alias_maximum' => 65535,
            'request_response_information' => 1,
            'request_problem_information' => 1,
        ])
        ->setSwooleConfig([
            'open_mqtt_protocol' => true,
            'package_max_length' => 2 * 1024 * 1024,
        ]);

    $client = new Client('127.0.0.1', 1883, $config);

    // Connect with MQTT 5.0 properties
    $response = $client->connect();
    echo "Connected with MQTT 5.0\n";

    // Publish with MQTT 5.0 properties
    $response = $client->publish(
        'iot/device/telemetry',
        json_encode([
            'temperature' => 25.5,
            'timestamp' => time()
        ]),
        1, // QoS
        0, // DUP
        0, // Retain
        [
            'topic_alias' => 1,                    // Use topic alias for efficiency
            'message_expiry_interval' => 300,      // Message expires in 5 minutes
            'payload_format_indicator' => 1,       // UTF-8 encoded payload
            'content_type' => 'application/json',  // Content type
            'response_topic' => 'iot/device/response',
            'correlation_data' => 'req_12345',
            'user_property' => [
                ['device_id', 'sensor_001'],
                ['location', 'building_a'],
            ],
        ]
    );

    var_dump($response);

    // Subsequent publishes can use empty topic with topic alias
    $response = $client->publish(
        '', // Empty topic, use alias
        json_encode(['temperature' => 26.0, 'timestamp' => time()]),
        1,
        0,
        0,
        ['topic_alias' => 1]
    );

    echo "Published with topic alias\n";

    $client->close();
});

```

--------------------------------

### MQTT over WebSocket Client (PHP)

Source: https://context7.com/simps/mqtt/llms.txt

Establishes an MQTT connection over WebSocket, suitable for browser environments and bypassing firewalls. This example utilizes the Simps WebSocketClient for MQTT and Swoole coroutines. It covers connecting, subscribing, publishing, and handling incoming messages, including QoS acknowledgments and keep-alive pings.

```php
<?php
use Simps\MQTT\WebSocketClient;
use Simps\MQTT\Config\ClientConfig;
use Simps\MQTT\Protocol\Types;
use Swoole\Coroutine;

Coroutine\run(function () {
    $config = new ClientConfig();
    $config->setClientId('websocket_client_001')
        ->setKeepAlive(60)
        ->setHeaders([
            'Sec-Websocket-Protocol' => 'mqtt',
            'Origin' => 'https://example.com',
        ]);

    // WebSocketClient(host, port, config, path, ssl)
    $client = new WebSocketClient(
        'broker.emqx.io',
        8083,
        $config,
        '/mqtt',  // WebSocket path
        false     // SSL enabled
    );

    $will = [
        'topic' => 'clients/websocket_001/status',
        'qos' => 0,
        'retain' => 0,
        'message' => 'disconnected',
    ];

    $client->connect(true, $will);
    echo "Connected via WebSocket\n";

    // Subscribe to topics
    $topics = ['chat/room/general' => 1];
    $client->subscribe($topics);

    // Publish a message
    $client->publish(
        'chat/room/general',
        json_encode(['user' => 'John', 'message' => 'Hello via WebSocket!']),
        1
    );

    // Message handling loop
    $timeSincePing = time();
    $duration = 30; // Run for 30 seconds
    $startTime = time();

    while ((time() - $startTime) < $duration) {
        try {
            $buffer = $client->recv();

            if ($buffer && $buffer !== true) {
                if ($buffer['type'] === Types::PUBLISH) {
                    $data = json_decode($buffer['message'], true);
                    echo "[{$buffer['topic']}] {$data['user']}: {$data['message']}\n";

                    if ($buffer['qos'] === 1) {
                        $client->send([
                            'type' => Types::PUBACK,
                            'message_id' => $buffer['message_id'],
                        ], false);
                    }
                }

                if ($buffer['type'] === Types::DISCONNECT) {
                    echo "WebSocket broker disconnected\n";
                    break;
                }
            }

            if ($timeSincePing <= (time() - $client->getConfig()->getKeepAlive())) {
                $client->ping();
                $timeSincePing = time();
            }

        } catch (Throwable $e) {
            echo "WebSocket error: " . $e->getMessage() . "\n";
            break;
        }
    }

    $client->close();
    echo "WebSocket connection closed\n";
});

```

--------------------------------

### Get Swoole Client Instance

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Retrieves the underlying Swoole Coroutine HTTP Client instance, allowing for direct interaction with Swoole's capabilities.

```APIDOC
## getClient()

### Description
Get an instance of `Swoole\Coroutine\Http\Client`.

### Method
GET

### Endpoint
/getClient

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```php
$swooleClient = $client->getClient();
// Now you can use $swooleClient for advanced Swoole operations
```

### Response
#### Success Response (200)
- **client** (Swoole\Coroutine\Http\Client) - The instance of the Swoole HTTP client.

#### Response Example
```json
{
  "client": "<Swoole\Coroutine\Http\Client object>"
}
```
```

--------------------------------

### Create and Format MQTT SubAck Message (PHP)

Source: https://github.com/simps/mqtt/blob/master/docs/en/message.md

This snippet shows how to instantiate a SubAck message, set QoS codes and message IDs, and format the message content for transmission. It includes examples for both MQTT 3.1.1 and MQTT 5.0, demonstrating the addition of protocol-specific properties like will delay interval and message expiry interval.

```php
use Simps\MQTT\Message\SubAck;
use Simps\MQTT\Protocol\ProtocolInterface;

$codes = [0];
$message_id = 8520;

$ack = new SubAck();
$ack->setCodes($codes)
    ->setMessageId($message_id);

$ack_data = $ack->getContents();
$ack_data = (string) $ack;

// MQTT5
$ack->setProtocolLevel(ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0)
    ->setCodes($codes)
    ->setMessageId($message_id)
    ->setProperties([
        'will_delay_interval' => 60,
        'message_expiry_interval' => 60,
    ]);

$ack_data = $ack->getContents();
$ack_data = (string) $ack;
```

--------------------------------

### Unsubscribe from MQTT Topics

Source: https://context7.com/simps/mqtt/llms.txt

Removes active subscriptions from one or more MQTT topics. This example first subscribes to a set of topics and then unsubscribes from a subset of them. Requires the Simps MQTT client library and Swoole.

```php
<?php
use Simps\MQTT\Client;
use Simps\MQTT\Config\ClientConfig;
use Simps\MQTT\Protocol\Types;
use Swoole\Coroutine;

Coroutine\run(function () {
    $config = new ClientConfig();
    $config->setClientId('client_unsubscribe')
        ->setKeepAlive(60);

    $client = new Client('127.0.0.1', 1883, $config);
    $client->connect();

    // First subscribe
    $topics = [
        'sensors/temperature' => 0,
        'sensors/humidity' => 1,
        'alerts/# ' => 0,
    ];
    $client->subscribe($topics);
    echo "Subscribed to topics\n";

    // Wait some time
    Coroutine::sleep(5);

    // Unsubscribe from specific topics
    $topicsToUnsubscribe = [
        'sensors/temperature',
        'alerts/#',
    ];

    $response = $client->unsubscribe($topicsToUnsubscribe);

    if ($response && $response['type'] === Types::UNSUBACK) {
        echo "Unsubscribed successfully\n";
        echo "Message ID: " . $response['message_id'] . "\n";
    }

    $client->close();
});

```

--------------------------------

### Get Underlying Swoole Client Instance

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Retrieves the underlying Swoole client instance, which can be either a Coroutine Client or a standard Swoole Client.

```php
<?php

$swooleClient = $client->getClient();

// Use $swooleClient for direct Swoole operations if needed

?>

```

--------------------------------

### Get Swoole HTTP Client Instance (PHP)

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Retrieves the underlying Swoole Coroutine HTTP Client instance used by the MQTT WebSocket client.

```php
<?php

// Assuming $client is an instance of Simps\MQTT\WebSocketClient

$swooleClient = $client->getClient();

if ($swooleClient) {
    // You can now interact with the Swoole client directly if needed
    // For example: $swooleClient->getPeerPort();
}

```

--------------------------------

### Client Initialization API

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Provides documentation for the MQTT client constructor, including parameters for host, port, client configuration, and client type.

```APIDOC
## __construct()

### Description
Create a MQTT client instance.

### Method
`__construct(string $host, int $port, ClientConfig $config, int $clientType = Client::COROUTINE_CLIENT_TYPE)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **host** (string) - Required - Broker's host.
- **port** (int) - Required - Broker's port.
- **config** (ClientConfig) - Required - ClientConfig object.
- **clientType** (int) - Optional - Set the client type, use a Coroutine Client or a Sync Client, the default is Coroutine Client. Sync Client for Fpm|Apache environments, mainly for `publish` messages, set to `Client::SYNC_CLIENT_TYPE`.

### Request Example
```php
$config = [
    'userName' => '',
    'password' => '',
    'clientId' => '',
    'keepAlive' => 10,
    'protocolName' => 'MQTT', // or MQIsdp
    'protocolLevel' => 4, // or 3, 5
    'properties' => [], // optional in MQTT5
    'delay' => 3000, // 3s
    'maxAttempts' => 5,
    '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 `protocolLevel` set.

### Response
None (This is a constructor).
```

--------------------------------

### Instantiate MQTT WebSocket Client (PHP)

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Creates an instance of the MQTT over WebSocket client. Requires broker host, port, client configuration, and optionally path and SSL settings.

```php
<?php

use Simps\MQTT\WebSocketClient;
use Simps\MQTT\Config\ClientConfig;

$config = [
    'userName' => '',
    'password' => '',
    'clientId' => '',
    'keepAlive' => 10,
    'protocolName' => 'MQTT', // or MQIsdp
    'protocolLevel' => 4, // or 3, 5
    'properties' => [], // optional in MQTT5
    'delay' => 3000, // 3s
    'maxAttempts' => 5,
    'swooleConfig' => []
];
$configObj = new ClientConfig($config);
$client = new WebSocketClient('broker.emqx.io', 8083, $configObj, '/mqtt');

```

--------------------------------

### WebSocketClient Constructor

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Initializes a new instance of the MQTT over WebSocket client. This involves specifying the broker's host, port, configuration, and WebSocket path, along with SSL options.

```APIDOC
## __construct() /api/simps/mqtt/WebSocketClient

### Description
Create an instance of the MQTT over WebSocket client.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```php
// Configuration array for the client
$config = [
    'userName' => '',
    'password' => '',
    'clientId' => '',
    'keepAlive' => 10,
    'protocolName' => 'MQTT', // or MQIsdp
    'protocolLevel' => 4, // or 3, 5
    'properties' => [], // optional in MQTT5
    'delay' => 3000, // 3s
    'maxAttempts' => 5,
    'swooleConfig' => []
];

// Create a ClientConfig object
$configObj = new Simps\MQTT\Config\ClientConfig($config);

// Instantiate the WebSocket client
$client = new Simps\MQTT\WebSocketClient('broker.emqx.io', 8083, $configObj, '/mqtt');
```

### Response
#### Success Response (200)
N/A (Constructor does not return a value)

#### Response Example
N/A
```

--------------------------------

### PHP Instantiate Debugging Tool

Source: https://github.com/simps/mqtt/blob/master/docs/en/debug.md

Demonstrates how to instantiate and use the `Debug` class from `SimpsMQTTTools` in PHP to view binary data. It shows setting the encoded data and then calling various dump methods to output the results.

```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();
```

--------------------------------

### Initialize Simps MQTT Client

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Creates an instance of the MQTT client. It requires the broker's host and port, a ClientConfig object for settings, and an optional client type (coroutine or sync). The ClientConfig object can be created from an array of configuration options.

```php
<?php

// Configuration array for the client
$config = [
    'userName' => '',
    'password' => '',
    'clientId' => '',
    'keepAlive' => 10,
    'protocolName' => 'MQTT', // or MQIsdp
    'protocolLevel' => 4, // or 3, 5
    'properties' => [], // optional in MQTT5
    'delay' => 3000, // 3s
    'maxAttempts' => 5,
    'swooleConfig' => []
];

// Create a ClientConfig object
$configObj = new Simps\MQTT\Config\ClientConfig($config);

// Instantiate the MQTT client
$client = new Simps\MQTT\Client('127.0.0.1', 1883, $configObj);

// The client will use the protocol resolution according to protocolLevel.
// For Fpm|Apache, use Client::SYNC_CLIENT_TYPE for publishing.
?>

```

--------------------------------

### Connect to MQTT Broker (PHP)

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Establishes a connection to the MQTT broker. Supports clean session and setting up a last will and testament message.

```php
<?php

// Assuming $client is an instance of Simps\MQTT\WebSocketClient

// Connect with clean session
$client->connect(); 

// Connect with a will message
$will = [
    'topic' => 'test/topic',
    'qos' => 1,
    'retain' => 0,
    'message' => 'Client disconnected unexpectedly',
    'properties' => [], // optional in MQTT5
];
$client->connect(true, $will);

```

--------------------------------

### Connect to Broker

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Establishes a connection to the MQTT broker. Supports clean session flag and optional WILL message configuration for disconnections.

```APIDOC
## connect()

### Description
Connect Broker.

### Method
POST

### Endpoint
/connect

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **clean** (bool) - Required - Whether to use a clean session. Default is `true`.
- **will** (array) - Optional - Configuration for a WILL message to be sent upon disconnection.
  - **topic** (string) - Required - The topic for the WILL message.
  - **qos** (int) - Optional - Quality of Service level for the WILL message. Default is 0.
  - **retain** (int) - Optional - Retain flag for the WILL message. Default is 0.
  - **message** (string) - Required - The content of the WILL message.
  - **properties** (array) - Optional - MQTT5 properties for the WILL message.

### Request Example
```php
// Example with clean session true
$client->connect(true);

// Example with clean session false and a WILL message
$will = [
    'topic' => 'disconnect/topic',
    'qos' => 1,
    'retain' => 0,
    'message' => 'Client disconnected unexpectedly',
    'properties' => [], // optional in MQTT5
];
$client->connect(false, $will);
```

### Response
#### Success Response (200)
Indicates a successful connection. The exact response format might depend on the underlying implementation but typically implies the connection is established.

#### Response Example
```json
{
  "status": "connected"
}
```
```

--------------------------------

### Build Basic MQTT Server with PHP/Swoole

Source: https://context7.com/simps/mqtt/llms.txt

This code implements a simple MQTT broker server using PHP and the Swoole extension. It handles client connections, subscriptions, message publishing, and disconnections according to the MQTT v3.1.1 protocol. The server relies on the Simps/MQTT library for protocol packing and unpacking.

```php
<?php
use Simps\MQTT\Protocol\Types;
use Simps\MQTT\Protocol\V3;

$server = new Swoole\Server('127.0.0.1', 1883, SWOOLE_BASE);

$server->set([
    'open_mqtt_protocol' => true,
    'worker_num' => 4,
    'package_max_length' => 2 * 1024 * 1024,
]);

// Store subscriptions
$subscriptions = [];

$server->on('connect', function ($server, $fd) {
    echo "Client #{$fd}: Connected\n";
});

$server->on('receive', function (Swoole\Server $server, $fd, $reactorId, $data) use (&$subscriptions) {
    try {
        $packet = V3::unpack($data);

        if (!is_array($packet) || !isset($packet['type'])) {
            $server->close($fd);
            return;
        }

        switch ($packet['type']) {
            case Types::CONNECT:
                // Validate protocol
                if ($packet['protocol_name'] !== 'MQTT') {
                    $server->close($fd);
                    return;
                }

                // Send CONNACK
                $server->send($fd, V3::pack([
                    'type' => Types::CONNACK,
                    'code' => 0,
                    'session_present' => 0,
                ]));

                echo "Client #{$fd}: Authenticated as {$packet['client_id']}\n";
                break;

            case Types::SUBSCRIBE:
                // Store subscriptions
                if (!isset($subscriptions[$fd])) {
                    $subscriptions[$fd] = [];
                }

                $codes = [];
                foreach ($packet['topics'] as $topic => $qos) {
                    $subscriptions[$fd][$topic] = $qos;
                    $codes[] = is_numeric($qos) && $qos < 3 ? $qos : 0x80;
                    echo "Client #{$fd}: Subscribed to {$topic} (QoS {$qos})\n";
                }

                // Send SUBACK
                $server->send($fd, V3::pack([
                    'type' => Types::SUBACK,
                    'message_id' => $packet['message_id'] ?? 0,
                    'codes' => $codes,
                ]));
                break;

            case Types::PUBLISH:
                echo "Client #{$fd}: Published to {$packet['topic']}\n";

                // Forward to subscribers
                foreach ($server->connections as $subFd) {
                    if ($subFd != $fd && isset($subscriptions[$subFd])) {
                        foreach ($subscriptions[$subFd] as $subTopic => $subQos) {
                            // Simple topic matching (no wildcards in this example)
                            if ($subTopic === $packet['topic']) {
                                $server->send($subFd, V3::pack([
                                    'type' => Types::PUBLISH,
                                    'topic' => $packet['topic'],
                                    'message' => $packet['message'],
                                    'qos' => min($packet['qos'], $subQos),
                                    'dup' => 0,
                                    'retain' => 0,
                                    'message_id' => $packet['message_id'] ?? 0,
                                ]));
                            }
                        }
                    }
                }

                // Send PUBACK for QoS 1
                if ($packet['qos'] === 1) {
                    $server->send($fd, V3::pack([
                        'type' => Types::PUBACK,
                        'message_id' => $packet['message_id'] ?? 0,
                    ]));
                }
                break;

            case Types::PINGREQ:
                $server->send($fd, V3::pack(['type' => Types::PINGRESP]));
                break;

            case Types::DISCONNECT:
                if (isset($subscriptions[$fd])) {
                    unset($subscriptions[$fd]);
                }
                $server->close($fd);
                break;

            case Types::UNSUBSCRIBE:
                if (isset($subscriptions[$fd])) {
                    foreach ($packet['topics'] as $topic) {
                        unset($subscriptions[$fd][$topic]);
                        echo "Client #{$fd}: Unsubscribed from {$topic}\n";
                    }
                }

                $server->send($fd, V3::pack([
                    'type' => Types::UNSUBACK,
                    'message_id' => $packet['message_id'] ?? 0,
                ]));
                break;
        }
    } catch (\Throwable $e) {
        echo "Error: {$e->getMessage()}\n";
        $server->close($fd);
    }
});

$server->on('close', function ($server, $fd) use (&$subscriptions) {
    if (isset($subscriptions[$fd])) {
        unset($subscriptions[$fd]);
    }
    echo "Client #{$fd}: Disconnected\n";
});

echo "MQTT Server started on 127.0.0.1:1883\n";
$server->start();

```

--------------------------------

### Docsify Configuration for PHP MQTT

Source: https://github.com/simps/mqtt/blob/master/docs/index.html

Configuration settings for the docsify static site generator. This includes setting the repository name, homepage, sidebar loading, search functionality, and custom plugins for copyright and text spacing.

```javascript
window.$docsify = {
  name: 'PHP MQTT',
  repo: 'simps/mqtt',
  homepage: 'zh-cn/README.md',
  loadSidebar: true,
  subMaxLevel: 3,
  loadNavbar: true,
  auto2top: true,
  coverpage: true,
  alias: {
    '/.*/_navbar.md': '/_navbar.md',
    '/_sidebar.md': '/zh-cn/_sidebar.md',
    '/zh-cn/.*/_sidebar.md': '/zh-cn/_sidebar.md',
    '/en/.*/_sidebar.md': '/en/_sidebar.md'
  },
  nameLink: {
    '/zh-cn/': '#/zh-cn/',
    '/en/': '#/en/',
    '/': '#/'
  },
  search: {
    depth: 6,
    noData: {
      '/en/': 'No results!',
      '/zh-cn/': '没有找到结果!',
      '/': '没有找到结果!'
    },
    paths: 'auto',
    placeholder: {
      '/en/': 'Type to Search',
      '/zh-cn/': '输入关键词搜索',
      '/': '输入关键词搜索'
    },
    pathNamespaces: ['/zh-cn', '/en']
  },
  plugins: [
    function (hook) {
      hook.beforeEach(function(html) {
        return ( html + '\n\n----\n\n' + 'Copyright © 2019-' + new Date().getFullYear() + ' <a href="https://github.com/sy-records" target="_blank" style="color: inherit; font-weight: normal; text-decoration: none;">Lu Fei</a>' );
      }), 
      hook.doneEach(function () {
        pangu.spacingElementByClassName('content')
      })
    }
  ]
}
```

--------------------------------

### Message Handling API

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Documentation for publishing messages to topics, subscribing to topics, and unsubscribing from topics.

```APIDOC
## publish()

### Description
Push a message to a topic.

### Method
`publish($topic, $message, $qos = 0, $dup = 0, $retain = 0, array $properties = [])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **topic** (string) - Required - The topic to publish the message to.
- **message** (string) - Required - The message content.
- **qos** (int) - Optional - Quality of Service level (0, 1, or 2). Default is 0.
- **dup** (int) - Optional - Duplicate delivery flag. Default is 0.
- **retain** (int) - Optional - Retain flag. Default is 0.
- **properties** (array) - Optional - Additional properties for the publish message (MQTT5).

### Request Example
```php
$client->publish('topic/test', 'Hello MQTT!');
$client->publish('topic/data', 'Important Data', 1, 0, 1);
```

### Response
None (Publish method typically returns void or a message ID).

## subscribe()

### Description
Subscribe to one topic or multiple topics.

### Method
`subscribe(array $topics, array $properties = [])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **topics** (array) - Required - An array of topics to subscribe to. The format depends on the MQTT protocol version:
  ```php
  // MQTT 3.x
  $topics = [
      // topic => Qos
      'topic1' => 0,
      'topic2' => 1,
  ];

  // MQTT 5.0
  $topics = [
      // topic => options
      '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,
      ],
  ];
  ```
- **properties** (array) - Optional - Additional properties for the subscribe message (MQTT5).

### Request Example
```php
// MQTT 3.x subscribe
$topics3 = ['topic1' => 0, 'topic2' => 1];
$client->subscribe($topics3);

// MQTT 5.0 subscribe
$topics5 = [
    'topic1' => ['qos' => 1],
    'topic2' => ['qos' => 2, 'no_local' => true]
];
$client->subscribe($topics5);
```

### Response
#### Success Response (200)
None (Subscribe method typically returns void or a subscription acknowledgement).

## unSubscribe()

### Description
Unsubscribe from a topic or multiple topics.

### Method
`unSubscribe(array $topics, array $properties = [])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **topics** (array) - Required - An array of topic names to unsubscribe from. Example: `['topic1', 'topic2']`.
- **properties** (array) - Optional - Additional properties for the unsubscribe message (MQTT5).

### Request Example
```php
$client->unSubscribe(['topic1', 'topic2']);
```

### Response
None (Unsubscribe method typically returns void).
```

--------------------------------

### Connect to MQTT Broker

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Establishes a connection to the MQTT broker. It accepts a boolean for a clean session and an optional array for will message configuration. A clean session defaults to true. The will message is sent by the broker if the client disconnects unexpectedly.

```php
<?php

// Connect with a clean session (default)
$client->connect();

// Connect without a clean session
$client->connect(false);

// Connect with a will message
$will = [
    'topic' => 'test/topic',
    'qos' => 1,
    'retain' => 0,
    'message' => 'Disconnected message',
    'properties' => [], // optional in MQTT5
];
$client->connect(true, $will);

?>

```

--------------------------------

### Subscribe to MQTT Topics

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Subscribes to one or multiple MQTT topics to receive messages. The format for specifying topics differs between MQTT 3.x and MQTT 5.0, with MQTT 5.0 allowing more detailed subscription options.

```php
<?php

// MQTT 3.x topic subscription
$topics_3x = [
    'topic1' => 0, // topic => Qos
    'topic2' => 1,
];
$client->subscribe($topics_3x);

// MQTT 5.0 topic subscription
$topics_5x = [
    '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,
    ],
];
$client->subscribe($topics_5x);

// Subscribe with MQTT5 properties
$properties = [
    'subscription_identifier' => 1
];
$client->subscribe($topics_5x, $properties);

?>

```

--------------------------------

### Perform MQTT Authentication

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Initiates an authentication exchange, a feature introduced in MQTT5. It takes an optional reason code and MQTT5 properties.

```php
<?php

use Simps\MQTT\Enum\ReasonCode;

// Perform authentication with success code
$client->auth(ReasonCode::SUCCESS);

// Perform authentication with properties
$properties = [
    'authentication_data' => 'binary_data'
];
$client->auth(ReasonCode::CONTINUE_AUTHENTICATION, $properties);

?>

```

--------------------------------

### MQTT 5.0 Protocol Pack/Unpack

Source: https://github.com/simps/mqtt/blob/master/docs/en/protocol.md

Package and parse data according to the MQTT 5.0 protocol. Uses static methods within the V5 class. Input for pack is an array, and output is a string. Input for unpack is a string, and output is an array.

```php
Simps\MQTT\Protocol\V5::pack(array $array)

Simps\MQTT\Protocol\V5::unpack(string $data)
```

--------------------------------

### Subscribe to Topics

Source: https://github.com/simps/mqtt/blob/master/docs/en/websocket.md

Subscribes to one or more MQTT topics. Supports different QoS levels and topic-specific options for MQTT 5.0.

```APIDOC
## subscribe()

### Description
Subscribe to one topic or multiple topics.

### Method
POST

### Endpoint
/subscribe

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **topics** (array) - Required - An array defining the topics and their subscription options.
  - For MQTT 3.x: `['topic1' => qos, 'topic2' => qos]`
  - For MQTT 5.0: `['topic1' => ['qos' => qos, ...], 'topic2' => ['qos' => qos, ...]]`
    - `qos` (int) - Required - Quality of Service level.
    - `no_local` (bool) - Optional - If true, messages published by the subscriber itself will not be delivered.
    - `retain_as_published` (bool) - Optional - If true, retain flag is sent to subscriber.
    - `retain_handling` (int) - Optional - Retain handling options.
- **properties** (array) - Optional - MQTT5 properties for the subscribe request.

### Request Example
```php
// MQTT 3.x example
$topics_3x = [
    'topic1' => 0,
    'topic2' => 1,
];
$client->subscribe($topics_3x);

// MQTT 5.0 example
$topics_5x = [
    '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,
    ],
];
$client->subscribe($topics_5x);
```

### Response
#### Success Response (200)
Indicates a successful subscription request.

#### Response Example
```json
{
  "status": "subscribed",
  "topic_ids": [1, 2] // IDs for the granted subscriptions
}
```
```

--------------------------------

### PHP Static Call for Hexadecimal ASCII Dump

Source: https://github.com/simps/mqtt/blob/master/docs/en/debug.md

Illustrates the static usage of `UnPackTool` from `SimpsMQTTTools` in PHP to perform a hexadecimal ASCII dump of binary data. This method is a convenient way to quickly inspect data without instantiation.

```php
use Simps\MQTT\Tools\UnPackTool;

echo UnPackTool::hexDumpAscii('0:simps-mqtt/user001/update{
  "msg": "hello, mqtt"
}');
```

--------------------------------

### Generate Client ID

Source: https://github.com/simps/mqtt/blob/master/docs/en/client.md

Generates a client identifier, optionally with a prefix.

```php
<?php

// Generate client ID with default prefix
$clientId = Simps\MQTT\Client::genClientID();

// Generate client ID with a custom prefix
$clientId = Simps\MQTT\Client::genClientID('MyClient_');

?>

```
Tokens:
Raw