README

A production-ready, highly scalable, and developer-friendly Laravel package that integrates MQTT into your applications. It provides a clean, event-driven, "Horizon-like" architecture for managing IoT streams and long-running MQTT daemons safely.

🚀 Features

• Clean Facade API: Effortless publishing and topic routing (Mqtt::publish, Mqtt::topic).
• Event & Job Dispatching: Map incoming MQTT topics directly to Laravel Events or Jobs, pushing heavy processing to your Queues natively.
• Robust Worker Daemon: Run php artisan mqtt:work under Supervisor with built-in memory protection, Graceful Shutdown (SIGTERM), and a Heartbeat Lock Manager to prevent duplicate processes.
• Auto Reconnect & Backoff: Configurable exponential backoff strategies to handle broker disconnections professionally.
• Topic Wildcards: Full support for MQTT wildcards (+ and #).
• Native Broadcasting: Seamlessly integrates with Laravel's native Broadcasting (broadcast(new Event)->toOthers()) using the custom mqtt driver!
• Premium Real-Time Dashboard: A built-in, Neo-Noir styled live metrics dashboard accessible out-of-the-box.
• Strictly Typed: Built on PHP 8.1 Enums for QosLevel and Protocols.

📦 Requirements

• PHP >= 8.1
• Laravel >= 9.0

🛠 Installation

You can install the package via composer:

composer require haider-kamran/laravel-mqtt

The package will automatically register its service provider. You should publish the configuration file and dashboard assets using:

php artisan vendor:publish --tag=mqtt-config
php artisan vendor:publish --tag=mqtt-views

⚙️ Configuration

After publishing, you can configure your broker credentials and connection settings in config/mqtt.php or your .env file:

MQTT_HOST=127.0.0.1
MQTT_PORT=1883
MQTT_CLIENT_ID=laravel-app
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_PROTOCOL=3.1.1
MQTT_KEEP_ALIVE=60
MQTT_RECONNECT=true
MQTT_RECONNECT_MAX_DELAY=60

📚 Usage

Publishing Messages

You can easily publish messages to any MQTT broker using the Mqtt facade. Arrays are automatically JSON-encoded.

use Haiderkamran\LaravelMqtt\Facades\Mqtt;
use Haiderkamran\LaravelMqtt\Enums\QosLevel;

Mqtt::publish('device/1/cmd', ['reboot' => true]);

// With QoS and Retain flag
Mqtt::publish('device/status', 'online', QosLevel::EXACTLY_ONCE, true);

Subscribing & Routing Topics

To listen to inbound topics, register your routes within your AppServiceProvider or a custom provider's boot method.

You can map topics directly to Laravel Events or Jobs. If a topic matches, the payload will be automatically dispatched to Laravel's native queue ecosystem!

use Haiderkamran\LaravelMqtt\Facades\Mqtt;
use App\Events\TemperatureUpdated;
use App\Jobs\ProcessDeviceData;

public function boot()
{
    // Exact Match -> Dispatches a Laravel Event
    Mqtt::topic('sensor/temp')->event(TemperatureUpdated::class);

    // Wildcard Match -> Dispatches a Laravel Job to the Queue
    Mqtt::topic('device/#')->dispatch(ProcessDeviceData::class);
    
    // Single-level wildcard support
    Mqtt::topic('room/+/lights')->dispatch(ProcessLightCommand::class);
}

Running the Worker Daemon

To start listening for the routed topics, spin up the built-in worker command:

php artisan mqtt:work

This acts exactly like a Laravel Queue worker. In production, you should use Supervisor to keep this process alive. The worker uses Laravel's Cache system as a Mutex Lock to ensure multiple instances of the worker don't accidentally run at the same time and duplicate messages.

If your server crashes hard and the lock gets stuck, you can gracefully purge the state using:

php artisan mqtt:clear

Native Laravel Broadcasting

The package registers a custom mqtt broadcast driver. This means you can use Laravel's standard broadcasting mechanics to publish to MQTT topics!

In your .env:

BROADCAST_DRIVER=mqtt

Now, any Laravel Event that implements ShouldBroadcast will natively publish its payload directly to your MQTT broker, converting Laravel dot notation channels (private-user.1) to MQTT slash notation (private-user/1) automatically!

📈 Real-Time Dashboard

The package comes with a highly optimized, beautifully crafted live dashboard. Once installed, simply navigate to:

👉 http://your-app.test/mqtt

You will see real-time, glassmorphic metrics of Messages Received, Published, Connection Drops, and the active status of your Worker Daemon.

📄 License

The MIT License (MIT). Please see LICENSE.md for more information.

👨‍💻 Author

Built with ❤️ by Kamran Haider.