README

A comprehensive Symfony bundle for MQTT (Message Queuing Telemetry Transport) messaging with full TLS support and easy integration.

✨ Features

🚀 Seamless Integration: Simple Symfony service injection and configuration
🔒 Enterprise TLS Support: Complete TLS/SSL configuration with certificate management
📦 JSON Message Handling: Built-in JSON serialization and deserialization
🎯 Full QoS Support: All MQTT Quality of Service levels (0, 1, 2)
🔧 Flexible Configuration: Environment-based configuration
📊 PSR-3 Logging: Comprehensive logging integration for debugging and monitoring
🛠️ Console Commands: Built-in CLI tools for testing and diagnostics

🚀 Coming Soon

We are actively working on expanding the bundle's capabilities to provide a seamless integration between Symfony and MQTT.
Below is our planned roadmap — stay tuned for updates!

Event Dispatcher integration for incoming messages
Multi-broker configuration support
More Console commands
MQTT v5 features (user properties, reason codes, etc.)
Symfony Flex recipe for quick installation & configuration
Examples & Docker setup for local development

📦 Installation

Step 1: Install via Composer

composer require mattia/mqtt-bundle

Step 2: Register the Bundle

Add the bundle to your config/bundles.php:

<?php

return [
    // ... other bundles
    Mattia\MqttBundle\MattiaMqttBundle::class => ['all' => true],
];

Step 3: Configure Environment Variables

Add the following to your .env file:

# MQTT Configuration
MQTT_HOST=localhost
MQTT_PORT=1883
MQTT_CLIENT_ID=symfony_mqtt_client
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_USE_TLS=false
MQTT_CONNECT_TIMEOUT=10

# TLS Configuration (only used when MQTT_USE_TLS=true)
MQTT_TLS_VERIFY_PEER=true
MQTT_TLS_VERIFY_PEER_NAME=true
MQTT_TLS_SELF_SIGNED_ALLOWED=false
MQTT_TLS_CA_FILE=
MQTT_TLS_CA_PATH=
MQTT_TLS_CLIENT_CERT_FILE=
MQTT_TLS_CLIENT_CERT_KEY_FILE=
MQTT_TLS_CLIENT_CERT_KEY_PASSPHRASE=

Step 4: Configure the Bundle

Create config/packages/mattia_mqtt.yaml:

mattia_mqtt:
  mqtt:
    host: "%env(MQTT_HOST)%"
    port: "%env(int:MQTT_PORT)%"
    client_id: "%env(MQTT_CLIENT_ID)%"
    username: "%env(MQTT_USERNAME)%"
    password: "%env(MQTT_PASSWORD)%"
    use_tls: "%env(bool:MQTT_USE_TLS)%"
    tls_verify_peer: "%env(bool:MQTT_TLS_VERIFY_PEER)%"
    tls_verify_peer_name: "%env(bool:MQTT_TLS_VERIFY_PEER_NAME)%"
    tls_self_signed_allowed: "%env(bool:MQTT_TLS_SELF_SIGNED_ALLOWED)%"
    tls_ca_file: "%env(resolve:MQTT_TLS_CA_FILE)%"
    tls_ca_path: "%env(resolve:MQTT_TLS_CA_PATH)%"
    tls_client_cert_file: "%env(resolve:MQTT_TLS_CLIENT_CERT_FILE)%"
    tls_client_cert_key_file: "%env(resolve:MQTT_TLS_CLIENT_CERT_KEY_FILE)%"
    tls_client_cert_key_passphrase: "%env(MQTT_TLS_CLIENT_CERT_KEY_PASSPHRASE)%"
    connect_timeout: "%env(int:MQTT_CONNECT_TIMEOUT)%"

🚀 Usage

Basic Integration

Inject the MQTT service into your controllers or services:

<?php

namespace App\Controller;

use Mattia\MqttBundle\Service\MqttService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class SensorController extends AbstractController
{
    public function __construct(
        private MqttService $mqttService
    ) {}

    public function publishSensorData(): void
    {
        // Publish a simple message
        $this->mqttService->publish('sensors/temperature', '25.5°C', 0, false);

        // Publish structured JSON data
        $this->mqttService->publishJson('sensors/data', [
            'temperature' => 25.5,
            'humidity' => 60,
            'timestamp' => date('c'),
            'location' => 'room-101'
        ]);
    }

    public function subscribeToSensorData(): void
    {
        $this->mqttService->subscribe('sensors/+', 0, function (string $topic, string $message, bool $retained) {
            // Handle received message
            $this->logger->info('Received sensor data', [
                'topic' => $topic,
                'message' => $message,
                'retained' => $retained
            ]);
        });
    }
}

Service API Reference

The MqttService provides a comprehensive API for MQTT operations:

📤 Publishing Messages

// Publish a simple string message
$mqttService->publish(string $topic, string $message, int $qos = 0, bool $retain = false): void

// Publish structured JSON data
$mqttService->publishJson(string $topic, array $data, int $qos = 0, bool $retain = false): void

📥 Subscribing to Topics

// Subscribe with callback function
$mqttService->subscribe(string $topic, int $qos = 0, callable $callback = null): void

// Subscribe with automatic JSON decoding
$mqttService->subscribeJson(string $topic, int $qos = 0, callable $callback = null): void

// Unsubscribe from a topic
$mqttService->unsubscribe(string $topic): void

🔌 Connection Management

// Check connection status
$mqttService->isConnected(): bool

// Disconnect from broker
$mqttService->disconnect(): void

🔒 TLS Configuration

// Get current TLS configuration for debugging
$mqttService->getTlsConfiguration(): array

🛠️ Console Commands

The bundle includes a built-in console command for testing connectivity:

# Basic connectivity test
php bin/console mqtt:ping

# Detailed test with configuration display
php bin/console mqtt:ping --details

📊 Debugging and Logging

Enable debug logging by configuring your logger to show MQTT-related messages:

# config/packages/monolog.yaml
monolog:
  channels: ["mqtt"]
  handlers:
    main:
      type: stream
      path: "%kernel.logs_dir%/%kernel.environment%.log"
      level: debug
      channels: ["mqtt"]
    console:
      type: console
      level: debug
      channels: ["mqtt"]

📋 Requirements

PHP: 8.1 or higher
Symfony: 6.4 or higher
MQTT Broker: Mosquitto, Eclipse Mosquitto, HiveMQ, or any MQTT broker

📄 License

This bundle is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

mattia / mqtt-bundle

Maintainers

Details