simps/mqtt Documentation

simps/mqtt is a PHP library providing MQTT protocol analysis and a coroutine-based client. It is designed for high-performance asynchronous environments (like Swoole).

Key Capabilities:

• Protocol Support: Supports MQTT versions 3.1, 3.1.1, and 5.0 (notably the first PHP library to support MQTT 5.0).
• Quality of Service: Supports QoS 0, QoS 1, and QoS 2.
• Transport: Supports MQTT over WebSocket.

Requirements:

• PHP >= 7.1
• Swoole >= 4.4.20

PHP MQTT is an MQTT protocol analysis and coroutine client for PHP. It is designed to support high-concurrency environments using coroutines and provides comprehensive support for various MQTT standards and transport methods.

Key Features:

• QoS Support: Supports Quality of Service levels 0, 1, and 2.
• Protocol Versions: Supports MQTT 3.1, 3.1.1, and 5.0 (notably the first PHP library to support MQTT 5.0).
• Transport: Supports MQTT over WebSocket.

The library provides support for the following protocol specifications and features:

• Protocol Versions: 3.1, 3.1.1, and 5.0 (notably the first PHP library to support 5.0).
• Quality of Service (QoS): Supports QoS 0, QoS 1, and QoS 2.
• Transport: Supports standard MQTT and MQTT over WebSocket.
• Runtime Requirements: Requires PHP >= 7.1 and Swoole >= 4.4.20.

To use the MQTT protocol analysis and coroutine client in your PHP project, install it using Composer.

composer require simps/mqtt

When acting as a Client, you can send a SubAck message. To receive the response as an array instead of raw data, pass true to the getContents() method.

// Passing true to getContents() returns an array
$client->send($ack->getContents(true), false);

When acting as a Server, you can send a SubAck message to a client by passing the file descriptor ($fd) and either the raw contents from getContents() or the string representation of the message object.

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

If you need to interact with the underlying transport layer, you can retrieve the Swoole Coroutine HTTP client.

Signature: Simps\MQTT\WebSocketClient->getClient(): Swoole\Coroutine\Http\Client

Utility methods for generating identifiers.

• Simps\MQTT\WebSocketClient::genClientID(string $prefix = 'Simps_'): Generates a unique Client ID using the provided prefix.
• Simps\MQTT\WebSocketClient->buildMessageId(): Generates a new Message ID for outgoing packets.

Establish a connection to the broker using the connect() method.

Signature: Simps\MQTT\WebSocketClient->connect(bool $clean = true, array $will = [])

• $clean: If true, starts a clean session (default).
• $will: An array defining the 'Last Will and Testament' message. If the client disconnects unexpectedly, the broker will send this message to other clients.

Will Message Format:

$will = [
    'topic' => '',
    'qos' => 1,
    'retain' => 0,
    'message' => '', // message content
    'properties' => [], // optional in MQTT5
];

$will = [
    'topic' => 'status/client1',
    'qos' => 1,
    'retain' => 0,
    'message' => 'offline',
    'properties' => [],
];
$client->connect(true, $will);

Use ping() to send a heartbeat to the broker to keep the connection alive. If $response is set to true, the client will call recv() once to wait for the heartbeat response.

$client->ping(true);

The Message API is primarily used to construct response messages, such as SubAck (Subscription Acknowledgement), to reply to ACKs in a Server or Client context. You can configure the acknowledgement codes, the message ID, and protocol-specific properties for MQTT 5.0.

use Simps//MQTT/Message/SubAck;
use Simps//MQTT/Protocol/ProtocolInterface;

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

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

// For MQTT 5.0, you can set additional properties
$ack->setProtocolLevel(ProtocolInterface::MQTT_PROTOCOL_LEVEL_5_0)
    ->setCodes($codes)
    ->setMessageId($message_id)
    ->setProperties([
        'will_delay_interval' => 60,
        'message_expiry_interval' => 60,
    ]);

// Retrieve the raw binary contents
$ack_data = $ack->getContents();

// Or cast to string to get the contents
$ack_data = (string) $ack;