php-mqtt/client

php-mqtt/client was created by, and is maintained by Marvin Mall. It allows you to connect to
an MQTT broker where you can publish messages and subscribe to topics. The current
implementation supports all QoS levels (with limitations).

Installation
The package is available on packagist.org and can be installed using composer:

composer require php-mqtt/client

The package requires PHP version 8.0 or higher.

Usage
In the following, only a few very basic examples are given. For more elaborate examples, have a
look at the php-mqtt/client-examples repository.

Publish
A very basic publish example using QoS 0 requires only three steps: connect, publish and
disconnect

$server = 'some-broker.example.com';
$port = 1883;
$clientId = 'test-publisher';

$mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);

$mqtt->connect();
$mqtt->publish('php-mqtt/client/test', 'Hello World!', 0);
$mqtt->disconnect();
If you do not want to pass a $clientId, a random one will be generated for you. This will
basically force a clean session implicitly.

Be also aware that most of the methods can throw exceptions. The above example does not add
any exception handling for brevity.

Subscribe
Subscribing is a little more complex than publishing as it requires to run an event loop which
reads, parses and handles messages from the broker:
$server = 'some-broker.example.com';
$port = 1883;
$clientId = 'test-subscriber';

$mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);

$mqtt->connect();
$mqtt->subscribe('php-mqtt/client/test', function ($topic, $message,
$retained, $matchedWildcards) {
echo sprintf("Received message on topic [%s]: %s\n", $topic, $message);
}, 0);
$mqtt->loop(true);
$mqtt->disconnect();
While the loop is active, you can use $mqtt->interrupt() to send an interrupt signal to the
loop. This will terminate the loop before it starts its next iteration. You can call this method
using pcntl_signal(SIGINT, $handler) for example:

pcntl_async_signals(true);

$clientId = 'test-subscriber';

$mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);

pcntl_signal(SIGINT, function (int $signal, $info) use ($mqtt) {
$mqtt->interrupt();
});
$mqtt->connect();
$mqtt->subscribe('php-mqtt/client/test', function ($topic, $message,
$retained, $matchedWildcards) {
echo sprintf("Received message on topic [%s]: %s\n", $topic, $message);
}, 0);
$mqtt->loop(true);
$mqtt->disconnect();

Client Settings
As shown in the examples above, the MqttClient takes the server, port and client id as first,
second and third parameter. As fourth parameter, the protocol level can be passed. Currently
supported is MQTT v3.1, available as constant MqttClient::MQTT_3_1. A fifth parameter
allows passing a repository (currently, only a MemoryRepository is available by default). Lastly,
a logger can be passed as sixth parameter. If none is given, a null logger is used instead.

Example:

$mqtt = new \PhpMqtt\Client\MqttClient(

$server,
$port,
$clientId,
\PhpMqtt\Client\MqttClient::MQTT_3_1,
new \PhpMqtt\Client\Repositories\MemoryRepository(),
new Logger()
);
The Logger must implement the Psr\Log\LoggerInterface.
Connection Settings
The connect() method of the MqttClient takes two optional parameters:

1. A ConnectionSettings instance
2. A boolean flag indicating whether a clean session should be requested (a random client
id does this implicitly)

Example:

$mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);

$connectionSettings = (new \PhpMqtt\Client\ConnectionSettings)

->setConnectTimeout(3)
->setUseTls(true)
->setTlsSelfSignedAllowed(true);

$mqtt->connect($connectionSettings, true);
The ConnectionSettings class provides a few settings through a fluent interface. The type
itself is immutable, and a new ConnectionSettings instance will be created for each added
option. This also prevents changes to the connection settings after a connection has been
established.

The following is a complete list of options with their respective default:

$connectionSettings = (new \PhpMqtt\Client\ConnectionSettings)

// The username used for authentication when connecting to the broker.

->setUsername(null)

// The password used for authentication when connecting to the broker.

->setPassword(null)

// Whether to use a blocking socket when publishing messages or not.

// Normally, this setting can be ignored. When publishing large messages
with multiple kilobytes in size,
// a blocking socket may be required if the receipt buffer of the broker
is not large enough.
//
// Note: This setting has no effect on subscriptions, only on the
publishing of messages.
->useBlockingSocket(false)

// The connect timeout defines the maximum amount of seconds the client
will try to establish
// a socket connection with the broker. The value cannot be less than 1
second.
->setConnectTimeout(60)

// The socket timeout is the maximum amount of idle time in seconds for
the socket connection.
 // If no data is read or sent for the given amount of seconds, the socket
will be closed.
// The value cannot be less than 1 second.
->setSocketTimeout(5)

// The resend timeout is the number of seconds the client will wait before
sending a duplicate
// of pending messages without acknowledgement. The value cannot be less
than 1 second.
->setResendTimeout(10)

// This flag determines whether the client will try to reconnect

automatically
// if it notices a disconnect while sending data.
// The setting cannot be used together with the clean session flag.
->setReconnectAutomatically(false)

// Defines the maximum number of reconnect attempts until the client gives
up.
// This setting is only relevant if setReconnectAutomatically() is set to
true.
->setMaxReconnectAttempts(3)

// Defines the delay between reconnect attempts in milliseconds.

// This setting is only relevant if setReconnectAutomatically() is set to
true.
->setDelayBetweenReconnectAttempts(0)

// The keep alive interval is the number of seconds the client will wait
without sending a message
// until it sends a keep alive signal (ping) to the broker. The value
cannot be less than 1 second
// and may not be higher than 65535 seconds. A reasonable value is 10
seconds (the default).
->setKeepAliveInterval(10)

// If the broker should publish a last will message in the name of the
client when the client
// disconnects abruptly, this setting defines the topic on which the
message will be published.
//
// A last will message will only be published if both this setting as well
as the last will
// message are configured.
->setLastWillTopic(null)

// If the broker should publish a last will message in the name of the
client when the client
// disconnects abruptly, this setting defines the message which will be
published.
//
// A last will message will only be published if both this setting as well
as the last will
// topic are configured.
->setLastWillMessage(null)
 // The quality of service level the last will message of the client will
be published with,
// if it gets triggered.
->setLastWillQualityOfService(0)

// This flag determines if the last will message of the client will be
retained, if it gets
// triggered. Using this setting can be handy to signal that a client is
offline by publishing
// a retained offline state in the last will and an online state as first
message on connect.
->setRetainLastWill(false)

// This flag determines if TLS should be used for the connection. The port
which is used to
// connect to the broker must support TLS connections.
->setUseTls(false)

// This flag determines if the peer certificate is verified, if TLS is

used.
->setTlsVerifyPeer(true)

// This flag determines if the peer name is verified, if TLS is used.

->setTlsVerifyPeerName(true)

// This flag determines if self signed certificates of the peer should be

accepted.
// Setting this to TRUE implies a security risk and should be avoided for
production
// scenarios and public services.
->setTlsSelfSignedAllowed(false)

// The path to a Certificate Authority certificate which is used to verify

the peer
// certificate, if TLS is used.
->setTlsCertificateAuthorityFile(null)

// The path to a directory containing Certificate Authority certificates

which are
// used to verify the peer certificate, if TLS is used.
->setTlsCertificateAuthorityPath(null)

// The path to a client certificate file used for authentication, if TLS

is used.
//
// The client certificate must be PEM encoded. It may optionally contain
the
// certificate chain of issuers.
->setTlsClientCertificateFile(null)

// The path to a client certificate key file used for authentication, if

TLS is used.
//
// This option requires ConnectionSettings::setTlsClientCertificateFile()
to be used as well.
->setTlsClientCertificateKeyFile(null)
 // The passphrase used to decrypt the private key of the client
certificate,
// which in return is used for authentication, if TLS is used.
//
// This option requires ConnectionSettings::setTlsClientCertificateFile()
and
// ConnectionSettings::setTlsClientCertificateKeyFile() to be used as
well.
->setTlsClientCertificateKeyPassphrase(null);

// The TLS ALPN is used to establish a TLS encrypted mqtt connection on

port 443,
// which usually is reserved for TLS encrypted HTTP traffic.
->setTlsAlpn(null);

Features
 Supported MQTT Versions

o v3 (just don't use v3.1 features like username & password)

o v3.1

o v3.1.1

o v5.0
 Transport

o TCP (unsecured)

o TLS (secured, verifies the peer using a certificate authority

file)