README

⚠️ Work in progress - use at own risk! ⚠️

php-mqtt/laravel-client was created by, and is maintained by Namoshek. It is a Laravel wrapper for the php-mqtt/client package and allows you to connect to an MQTT broker where you can publish messages and subscribe to topics.

Installation

composer require php-mqtt/laravel-client

The package will register itself through Laravel auto discovery of packages. Registered will be the service provider as well as an MQTT facade.

After installing the package, you should publish the configuration file using

php artisan vendor:publish --provider="PhpMqtt\Client\MqttClientServiceProvider"

and change the configuration in config/mqtt-client.php according to your needs.

Configuration

The package allows you to configure multiple named connections. An initial example can be found in the published configuration file. Except for the host parameter, all configuration options are entirely optional and come with the defaults provided to the env() helper in the example configuration file (no default means null).

An example configuration of two connections, where one is meant for sharing public data and one for private data, could look like the following:

'default_connection' => 'private',

'connections' => [
    'private' => [
        'host' => 'mqtt.example.com',
        'port' => 1883,
    ],
    'public' => [
        'host' => 'test.mosquitto.org',
        'port' => 1883,
    ],
],

In this example, the private connection is the default one.

Usage

Publish (QoS level 0)

Publishing a message with QoS level 0 is quite easy and can be done in a single command:

use PhpMqtt\Client\Facades\MQTT;

MQTT::publish('some/topic', 'Hello World!');

If needed, the connection name can be passed as third parameter:

use PhpMqtt\Client\Facades\MQTT;

MQTT::publish('some/topic', 'Hello World!', 'public');

Using MQTT::publish($topic, $message) will implicitly call MQTT::connection(), but the connection will not be closed after usage. If you want to close the connection manually because your script does not need the connection any more, you can call MQTT:close() (optionally with the connection name as a parameter). Please also note that using MQTT::publish($topic, $message) will always use QoS level 0. If you need a different QoS level, then please follow the instructions below.

Publish (QoS level 1 & 2)

Different to QoS level 0, we need to run an event loop in order for QoS 1 and 2 to work. This is because with a one-off command we cannot guarantee that a message reaches it's target. The event loop will ensure a published message gets sent again if no acknowledgment is returned by the broker within a grace period (in case of QoS level 1). Also handled by the event loop will be the release of packages in case of QoS level 2.

use PhpMqtt\Client\Facades\MQTT;

$mqtt = MQTT::connection();
$mqtt->publish('some/topic', 'foo', 1);
$mqtt->publish('some/other/topic', 'bar', 2);
$mqtt->loop(true);

In order to escape the loop, you can call $mqtt->interrupt() which will exit the loop during the next iteration. The method can for example be called in a registered signal handler:

pcntl_signal(SIGINT, function (int $signal, $info) use ($mqtt) {
    $mqtt->interrupt();
});

Very similar to publishing with QoS level 1 and 2, subscribing requires to run an event loop. But before running the loop, topics need to be subscribed to:

use PhpMqtt\Client\Facades\MQTT;

$mqtt = MQTT::connection();
$mqtt->subscribe('some/topic', function (string $topic, string $message) {
    echo sprintf('Received QoS level 1 message on topic [%s]: %s', $topic, $message);
}, 1);
$mqtt->loop(true);

Features

This library allows you to use all the features provided by php-mqtt/client.

License

php-mqtt/laravel-client is open-sourced software licensed under the MIT license.

shineit / mqtt-laravel-client

Maintainers

Details