Php-Mqtt Laravel Client

https://github.com/php-mqtt/laravel-client
Admin
A Laravel wrapper for the php-mqtt/client package, allowing connection to an MQTT broker to publish...
Tokens:32,091
Snippets:173
Trust Score:5.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install php-mqtt/laravel-client via Composer

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Installs the package from Packagist. The package registers itself through Laravel auto discovery, including the service provider and the MQTT facade.

```bash
composer require php-mqtt/laravel-client
```

--------------------------------

### Example MQTT client configuration with two connections

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Shows a configuration with two named connections: 'private' (default) and 'public'. Most options are optional with sane defaults, especially connection_settings. It is recommended to use environment variables for configuration.

```php
'default_connection' => 'private',

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

--------------------------------

### CustomConnectionManager override example

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Shows how to subclass ConnectionManager and override buildConnectionSettings to customize settings, e.g., forcing a longer keep-alive interval. The example calls parent::buildConnectionSettings and then modifies the returned settings.

```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\ConnectionSettings;

class CustomConnectionManager extends ConnectionManager
{
    protected function buildConnectionSettings(array $config): ConnectionSettings
    {
        $settings = parent::buildConnectionSettings($config);

        // e.g. force a longer keep-alive for this application
        return $settings->setKeepAliveInterval(30);
    }
}
```

--------------------------------

### loop

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Starts the event loop for network read/write operations. It returns when the client disconnects, or optionally exits as soon as all resend queues are cleared.

```APIDOC
## loop

### Description
Starts the event loop for network read/write operations. It returns when the client disconnects, or optionally exits as soon as all resend queues are cleared.

### Method
loop

### Signature
`loop($allowReconnects, $exitWhenQueuesEmpty)`

### Parameters
- **$allowReconnects** (bool) - Required - Whether reconnects are allowed.
- **$exitWhenQueuesEmpty** (bool) - Optional - If true, exits the loop as soon as all resend queues are cleared (acknowledgements received).

### Usage Example
```php
$mqtt->loop(true);
$mqtt->loop(true, true);
```
```

--------------------------------

### connection() method signature

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Gets a connection by name, falling back to default_connection. Throws exceptions for missing connections, config issues, broker failures, unsupported protocols, or binding resolution failures.

```php
/**
 * Gets the connection with the specified name.
 *
 * @param string|null $name
 * @return MqttClientContract
 * @throws BindingResolutionException
 * @throws ConfigurationInvalidException
 * @throws ConnectingToBrokerFailedException
 * @throws ConnectionNotAvailableException
 * @throws ProtocolNotSupportedException
 */
public function connection(?string $name = null): MqttClientContract
```

--------------------------------

### Basic usage: resolve via container, subscribe, run loop

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Resolves ConnectionManager from the container, gets the default connection, subscribes to a topic, and runs the loop. The callback prints received messages.

```php
use PhpMqtt\Client\ConnectionManager;

/** @var ConnectionManager $manager */
$manager = app(ConnectionManager::class);

/** @var \PhpMqtt\Client\Contracts\MqttClient $client */
$client = $manager->connection();          // default connection
$client->subscribe('some/topic', function (string $topic, string $message) {
    echo sprintf('Received on [%s]: %s', $topic, $message);
}, 1);
$client->loop(true);
```

--------------------------------

### Catching via shared base class MqttClientException

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionNotAvailableException.md

Example of catching ConnectionNotAvailableException via its parent class MqttClientException, which also catches protocol-level exceptions from php-mqtt/client.

```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\MqttClientException;

try {
    MQTT::publish('some/topic', 'Hello World!', false, 'unknown-connection');
} catch (MqttClientException $e) {
    // Catches ConnectionNotAvailableException as well as the protocol-level
    // exceptions raised by php-mqtt/client (ConfigInvalidException,
    // ConnectingToBrokerFailedException, DataTransferException, ...)
    report($e);
}
```

--------------------------------

### Catch BadFunctionCallException when booting provider outside Laravel

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/errors.md

Catch \BadFunctionCallException when calling $provider->boot() outside a Laravel context. This exception is thrown at src/MqttClientServiceProvider.php:37-39 when the config_path() helper is missing, with the message 'config_path() function not found. Is the Laravel framework installed?'. Normal Laravel apps never see this condition.

```php
// Only relevant when booting the provider outside Laravel; normal apps never see this.
try {
    $provider->boot();
} catch (\BadFunctionCallException $e) {
    // 'config_path() function not found. Is the Laravel framework installed?'
}
```

--------------------------------

### Catching ConnectionNotAvailableException

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/errors.md

Catch `ConnectionNotAvailableException` when publishing to an unknown connection. It extends `MqttClientException`, so that can be caught instead. The example logs the error message.

```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;

try {
    MQTT::publish('some/topic', 'Hello World!', false, 'unknown');
} catch (ConnectionNotAvailableException $e) {
    Log::error('Unknown MQTT connection: ' . $e->getMessage());
}
```

--------------------------------

### Catching ConnectionNotAvailableException after requesting unknown connection

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionNotAvailableException.md

Example of catching ConnectionNotAvailableException when calling MQTT::connection() with a name not present in the connections config. The exception message includes the requested name.

```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;

try {
    $mqtt = MQTT::connection('not-configured');
} catch (ConnectionNotAvailableException $e) {
    // $e->getMessage() === 'An MQTT connection with the name [not-configured] could not be found.'
    Log::error('MQTT connection missing: ' . $e->getMessage());
}
```

--------------------------------

### connection(?string $name = null): MqttClientContract

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Gets the connection with the specified name. Falls back to the default connection if no name is given, and returns a connected MQTT client. Throws exceptions if the connection is not available or cannot be established.

```APIDOC
## connection(?string $name = null): MqttClientContract

### Description
Gets the connection with the specified name. Falls back to the default connection if no name is given, and returns a connected MQTT client. Throws exceptions if the connection is not available or cannot be established.

### Method
Method

### Signature
```php
public function connection(?string $name = null): MqttClientContract
```

### Parameters
- **$name** (string|null) - Optional - Default: `null` - Connection name from the `connections` config block. `null` resolves to `default_connection`.

### Returns
- **MqttClientContract** (`PhpMqtt\Client\Contracts\MqttClient`, aliased as `MqttClientContract`) — a connected MQTT client.

### Throws
- **ConnectionNotAvailableException** - The connection name is not defined in `connections` config
- **ConfigurationInvalidException** - Config validation failure in `php-mqtt/client` during connect
- **ConnectingToBrokerFailedException** - Broker could not be reached/connected
- **ProtocolNotSupportedException** - The configured protocol constant is not supported
- **BindingResolutionException** - Container cannot resolve the repository/logger binding

### Behavior
1. Falls back to `$defaultConnection` when `$name` is `null`.
2. If a cached connection with that name exists but `isConnected()` is `false`, it is removed — "Doing this instead of simply reconnecting ensures the caller will get a fresh connection" (source comment).
3. Creates the connection on first use via `createConnection()` and caches it.
4. Returns the cached instance.

### Example — basic usage (resolve via container, subscribe, run loop)
```php
use PhpMqtt\Client\ConnectionManager;

/** @var ConnectionManager $manager */
$manager = app(ConnectionManager::class);

/** @var \PhpMqtt\Client\Contracts\MqttClient $client */
$client = $manager->connection();          // default connection
$client->subscribe('some/topic', function (string $topic, string $message) {
    echo sprintf('Received on [%s]: %s', $topic, $message);
}, 1);
$client->loop(true);
```

### Example — error handling (missing connection + broker unreachable)
```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;

$manager = app(ConnectionManager::class);

try {
    $client = $manager->connection('missing');
} catch (ConnectionNotAvailableException $e) {
    // 'missing' is not a key in config('mqtt-client.connections')
} catch (ConnectingToBrokerFailedException $e) {
    // host/port from the config could not be connected
}
```
```

--------------------------------

### boot() method signature

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Defines the boot method for the service provider. Throws BadFunctionCallException if config_path() is missing, and publishes config when running in console.

```php
/**
 * Bootstrap any application services.
 *
 * @return void
 * @throws \BadFunctionCallException
 */
public function boot(): void
```

--------------------------------

### Constructor call for MqttClient

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Instantiates the MqttClient with host, port, client ID, protocol, repository, and logger. The protocol defaults to MQTT_3_1, and the repository defaults to MemoryRepository. The logger is null if logging is disabled.

```php
$client = new MqttClient($host, $port, $clientId, $protocol, $repository, $logger);
```

--------------------------------

### Basic usage of MQTT::connection()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Shows how to obtain a connection using the facade, subscribe to a topic, and run the event loop. Uses 'default_connection' when no name is given, or a named connection like 'private'. Requires the loop for incoming messages.

```php
use PhpMqtt\Client\Facades\MQTT;

/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
$mqtt = MQTT::connection();            // uses 'default_connection' from config
$mqtt = MQTT::connection('private');   // uses the 'private' connection config

// Subscribe and run the event loop (requires the loop for incoming messages):
$mqtt->subscribe('some/topic', function (string $topic, string $message) {
    echo sprintf('Received message on topic [%s]: %s', $topic, $message);
}, 1);
$mqtt->loop(true);
```

--------------------------------

### Publish MQTT client configuration

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Publishes the configuration file to config/mqtt-client.php using the specified provider and tag. After publishing, edit the configuration according to your needs.

```bash
php artisan vendor:publish --provider="PhpMqtt\Client\MqttClientServiceProvider" --tag="config"
```

--------------------------------

### Subscribe to topic with event loop

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Subscribes to a topic with QoS 1 and runs the event loop to receive messages.

```php
use PhpMqtt\Client\Facades\MQTT;

/** @var \PhpMqtt\Client\Contracts\MqttClient $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);
```

--------------------------------

### Publish messages with QoS 1 and 2 using event loop

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Publishes messages with QoS 1 and 2 using the MQTT connection and runs the event loop to ensure delivery. The loop exits when all resend queues are cleared.

```php
use PhpMqtt\Client\Facades\MQTT;

/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
$mqtt = MQTT::connection();
$mqtt->publish('some/topic', 'foo', 1);
$mqtt->publish('some/other/topic', 'bar', 2, true); // Retain the message
$mqtt->loop(true);
```

--------------------------------

### Import MqttClient Contract and Concrete Class

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Imports the MqttClient contract and concrete class in this repository. The contract is used for type-hinting connections and facade stubs, while the concrete class is produced by this package.

```php
use PhpMqtt\Client\Contracts\MqttClient as MqttClientContract;       // src/ConnectionManager.php:10
use PhpMqtt\Client\Contracts\MqttClient;                              // src/Facades/MQTT.php:9
```

--------------------------------

### register() method signature

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Defines the register method for the service provider. It merges the package config and calls registerServices(). No parameters, returns void.

```php
/**
 * Register the service provider.
 *
 * @return void
 */
public function register(): void
```

--------------------------------

### Error handling for publish()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Demonstrates catching exceptions thrown by publish(). ConnectingToBrokerFailedException indicates the broker is unreachable, DataTransferException indicates a transfer failure after connection, and ConnectionNotAvailableException indicates the specified connection is not configured.

```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;
use PhpMqtt\Client\Exceptions\DataTransferException;

$manager = app(ConnectionManager::class);

try {
    $manager->publish('telemetry/stats', $payload, false, 'private');
} catch (ConnectingToBrokerFailedException $e) {
    // broker unreachable — connection could not be established
} catch (DataTransferException $e) {
    // connection established but the publish transfer failed
} catch (\PhpMqtt\Client\Exceptions\ConnectionNotAvailableException $e) {
    // 'private' connection is not configured
}
```

--------------------------------

### Basic usage of MQTT::publish()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Publishes a message with QoS 0. The first call uses the default connection; the second uses the retain flag and an explicit connection name 'public'.

```php
use PhpMqtt\Client\Facades\MQTT;

// Publish with QoS 0, retain = false, default connection:
MQTT::publish('some/topic', 'Hello World!');

// Publish with the retain flag and an explicit connection:
MQTT::publish('some/topic', 'Hello World!', true, 'public');
```

--------------------------------

### connect

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Connects the client to the broker using the provided connection settings and clean session flag.

```APIDOC
## connect

### Description
Connects the client to the broker using the provided connection settings and clean session flag.

### Method
connect

### Signature
`connect($settings, $cleanSession)`

### Parameters
- **$settings** (ConnectionSettings) - Required - The connection settings.
- **$cleanSession** (bool) - Required - Whether to start a clean session.

### Usage Example
```php
$client->connect($settings, $cleanSession);
```
```

--------------------------------

### Resolving bound services in application code

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Shows how to resolve the ConnectionManager and Repository bindings via the app() helper. The manager's connection() method returns a connected MqttClient.

```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\Contracts\Repository;

$manager = app(ConnectionManager::class);              // bound factory above
$repo    = app(Repository::class);                     // resolves to MemoryRepository

$client = $manager->connection();                      // connected MqttClient
```

--------------------------------

### connection() method annotation

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Static method annotation from the facade's @method declaration. Returns an MqttClient instance for the given connection name, or the default connection if null. Throws exceptions if the connection is not configured or the broker is unreachable.

```php
@method static MqttClient connection(string|null $name = null)
```

--------------------------------

### Basic usage of publish()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Shows how to publish a message using the ConnectionManager from the Laravel container. The first call publishes with QoS 0 and no retain flag; the second publishes with retain=true and an explicit connection named 'public'. The connection is not closed after publishing.

```php
use PhpMqtt\Client\ConnectionManager;

$manager = app(ConnectionManager::class);

$manager->publish('some/topic', 'Hello World!');         // QoS 0, not retained
$manager->publish('some/topic', 'Hello World!', true, 'public'); // retained, explicit connection
```

--------------------------------

### publish() method signature annotation

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Exact @method annotation from the facade, declaring the static publish() method with parameters $topic, $message, $retain, and $connection.

```php
@method static void publish(string $topic, string $message, bool $retain = false, string|null $connection = null)
```

--------------------------------

### Publish message with retain flag and connection name

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Publishes a message with QoS 0, passing the retain flag (default false) as third parameter and connection name as fourth parameter.

```php
use PhpMqtt\Client\Facades\MQTT;

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

--------------------------------

### Publish message with QoS 0 using MQTT facade

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Publishes a message with QoS level 0 using the MQTT facade. The connection is not closed after usage; call MQTT::disconnect() manually if needed.

```php
use PhpMqtt\Client\Facades\MQTT;

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

--------------------------------

### Error handling for unknown connection name

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Shows how to catch exceptions when calling MQTT::connection() with an unconfigured name or when the broker is unreachable. Handles ConnectionNotAvailableException and ConnectingToBrokerFailedException.

```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;

try {
    $mqtt = MQTT::connection('not-configured');
} catch (ConnectionNotAvailableException $e) {
    // 'not-configured' is not a key in config('mqtt-client.connections')
    report($e);
} catch (ConnectingToBrokerFailedException $e) {
    // The broker at the configured host:port could not be reached
    report($e);
}
```

--------------------------------

### registerServices() method implementation

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Protected method that registers two container bindings: ConnectionManager via a factory closure reading config('mqtt-client') and Repository to MemoryRepository. Called during service provider registration.

```php
/**
 * Registers the services offered by this package.
 *
 * @return void
 */
protected function registerServices(): void
{
    $this->app->bind(ConnectionManager::class, function (Application $app) {
        $config = $app->make('config')->get('mqtt-client', []);

        return new ConnectionManager($app, $config);
    });

    $this->app->bind(Repository::class, MemoryRepository::class);
}
```

--------------------------------

### MqttClientServiceProvider class implementation

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Registers the php-mqtt/laravel-client package within a Laravel application. Merges the package configuration, binds ConnectionManager and the Repository contract in the container, and publishes the config file for vendor:publish. Throws BadFunctionCallException if config_path() is not available. The file lacks declare(strict_types=1).

```php
/**
 * Registers the php-mqtt/laravel-client within the application.
 *
 * @package PhpMqtt\Client
 */
class MqttClientServiceProvider extends ServiceProvider
{
    /**
     * Register the service provider.
     *
     * @return void
     */
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__ . '/../config/mqtt-client.php', 'mqtt-client');

        $this->registerServices();
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     * @throws \BadFunctionCallException
     */
    public function boot(): void
    {
        if (!function_exists('config_path')) {
            throw new \BadFunctionCallException('config_path() function not found. Is the Laravel framework installed?');
        }

        if ($this->app->runningInConsole()) {
            $this->publishes([__DIR__ . '/../config/mqtt-client.php' => config_path('mqtt-client.php')], 'config');
        }
    }

    /**
     * Registers the services offered by this package.
     *
     * @return void
     */
    protected function registerServices(): void
    {
        $this->app->bind(ConnectionManager::class, function (Application $app) {
            $config = $app->make('config')->get('mqtt-client', []);

            return new ConnectionManager($app, $config);
        });

        $this->app->bind(Repository::class, MemoryRepository::class);
    }
}
```

--------------------------------

### Using MQTT facade with named connections

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/configuration.md

Shows how to use the MQTT facade to access the default connection, a specific named connection, and publish to a topic on a specific connection. The default connection is 'private' as set in the configuration.

```php
use PhpMqtt\Client\Facades\MQTT;

MQTT::connection();                 // 'private' (default_connection)
MQTT::connection('public');         // 'public'
MQTT::publish('some/topic', 'x', true, 'public'); // publish on 'public'
```

--------------------------------

### Error handling for MQTT::publish() in request context

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Catches ConnectionNotAvailableException and DataTransferException when publishing. Logs errors for missing connection configuration or transfer failures.

```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\DataTransferException;

try {
    MQTT::publish('alerts/server-down', $message, true, 'private');
} catch (ConnectionNotAvailableException $e) {
    Log::error('MQTT connection not configured: ' . $e->getMessage());
} catch (DataTransferException $e) {
    // e.g. publish failed while transferring data to the broker
    Log::error('MQTT publish failed: ' . $e->getMessage());
}
```

--------------------------------

### publish

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Publishes a message to a topic with a specified QoS level and retain flag. The event loop must run afterwards for acknowledgements when using QoS 1 or 2.

```APIDOC
## publish

### Description
Publishes a message to a topic with a specified QoS level and retain flag. The event loop must run afterwards for acknowledgements when using QoS 1 or 2.

### Method
publish

### Signature
`publish($topic, $message, $qos, $retain)`

### Parameters
- **$topic** (string) - Required - The topic to publish to.
- **$message** (string) - Required - The message payload.
- **$qos** (int) - Required - QoS level (0, 1, or 2). Use `MqttClient::QOS_AT_MOST_ONCE` for QoS 0.
- **$retain** (bool) - Required - Whether the message should be retained by the broker.

### Usage Example
```php
$mqtt->publish('some/topic', 'foo', 1);
$mqtt->publish('some/other/topic', 'bar', 2, true);
```

### Notes
- For QoS 1/2, the loop resends until the broker acknowledges, so calling `loop()` is required.
```

--------------------------------

### publish(string $topic, string $message, bool $retain = false, ?string $connection = null): void

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Publishes a message on the given connection with QoS level 0. The connection is resolved (opened if needed) and the message is sent to the specified MQTT topic. The connection is not closed after publishing.

```APIDOC
## publish(string $topic, string $message, bool $retain = false, ?string $connection = null): void

### Description
Publishes a message on the given connection with QoS level 0. The connection is resolved (opened if needed) and the message is sent to the specified MQTT topic. The connection is not closed after publishing.

### Method
publish

### Signature
```php
public function publish(string $topic, string $message, bool $retain = false, ?string $connection = null): void
```

### Parameters
- **$topic** (string) - Required - MQTT topic to publish to.
- **$message** (string) - Required - Payload to publish.
- **$retain** (bool) - Optional - Retain flag forwarded to the broker. Default: `false`.
- **$connection** (string|null) - Optional - Connection name; `null` resolves to `default_connection`. Default: `null`.

### Returns
- **void** - No return value.

### Throws
- **BindingResolutionException** - Thrown when the connection cannot be resolved.
- **ConfigurationInvalidException** - Thrown when the connection configuration is invalid.
- **ConnectingToBrokerFailedException** - Thrown when the connection to the broker fails.
- **ConnectionNotAvailableException** - Thrown when the specified connection is not available.
- **DataTransferException** - Thrown when the publish transfer fails.
- **ProtocolNotSupportedException** - Thrown when the protocol is not supported.
- **RepositoryException** - Thrown when a repository error occurs.

### Example - Basic Usage
```php
use PhpMqtt\Client\ConnectionManager;

$manager = app(ConnectionManager::class);

$manager->publish('some/topic', 'Hello World!');         // QoS 0, not retained
$manager->publish('some/topic', 'Hello World!', true, 'public'); // retained, explicit connection
```

### Example - Error Handling
```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;
use PhpMqtt\Client\Exceptions\DataTransferException;

$manager = app(ConnectionManager::class);

try {
    $manager->publish('telemetry/stats', $payload, false, 'private');
} catch (ConnectingToBrokerFailedException $e) {
    // broker unreachable — connection could not be established
} catch (DataTransferException $e) {
    // connection established but the publish transfer failed
} catch (\PhpMqtt\Client\Exceptions\ConnectionNotAvailableException $e) {
    // 'private' connection is not configured
}
```
```

--------------------------------

### buildConnectionSettings method signature

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Protected method that builds ConnectionSettings from the connection config. It chains setters for timeouts, TLS, last will, and auto-reconnect options, applying casts and defaults as documented. No exceptions are declared.

```php
/**
 * Builds the {@see ConnectionSettings} for the connection specified by the given config.
 *
 * @param array $config
 * @return ConnectionSettings
 */
protected function buildConnectionSettings(array $config): ConnectionSettings
```

--------------------------------

### MQTT::connection()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Retrieves a connected MQTT client instance based on the provided connection name. If no name is given, the default connection is used.

```APIDOC
## MQTT::connection()

### Description
Retrieves a connected MQTT client instance based on the provided connection name. If no name is given, the default connection is used.

### Method
Static method

### Signature
`@method static MqttClient connection(string|null $name = null)`

### Parameters
- `$name` (string|null) - Optional - Name of a connection defined in `connections` of `config/mqtt-client.php`. `null` resolves to the `default_connection`.

### Returns
- `MqttClient` - A connected `PhpMqtt\Client\Contracts\MqttClient` instance (concretely a `PhpMqtt\Client\MqttClient` connected with the settings of the named connection).

### Throws
- `BindingResolutionException`
- `ConfigurationInvalidException`
- `ConnectingToBrokerFailedException`
- `ConnectionNotAvailableException`
- `ProtocolNotSupportedException`

### Example
```php
use PhpMqtt\Client\Facades\MQTT;

/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
$mqtt = MQTT::connection();            // uses 'default_connection' from config
$mqtt = MQTT::connection('private');   // uses the 'private' connection config

// Subscribe and run the event loop (requires the loop for incoming messages):
$mqtt->subscribe('some/topic', function (string $topic, string $message) {
    echo sprintf('Received message on topic [%s]: %s', $topic, $message);
}, 1);
$mqtt->loop(true);
```

### Error Handling Example
```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;

try {
    $mqtt = MQTT::connection('not-configured');
} catch (ConnectionNotAvailableException $e) {
    // 'not-configured' is not a key in config('mqtt-client.connections')
    report($e);
} catch (ConnectingToBrokerFailedException $e) {
    // The broker at the configured host:port could not be reached
    report($e);
}
```
```

--------------------------------

### Basic usage of MQTT::disconnect()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Shows fire-and-forget publish opening the default connection implicitly, then closing it with disconnect() and closing a named connection.

```php
use PhpMqtt\Client\Facades\MQTT;

// Fire-and-forget publish opens the default connection implicitly:
MQTT::publish('some/topic', 'Hello World!');

// ... later, when the script no longer needs the connection:
MQTT::disconnect();             // closes the default connection
MQTT::disconnect('public');     // closes the named 'public' connection
```

--------------------------------

### Full connection block with TLS, auth, and last will

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/configuration.md

Complete configuration for a secure MQTT connection using TLS, authentication, and a last will message. Includes protocol version, client ID, logging, repository, timeouts, auto-reconnect, and TLS verification settings. Environment variables are used for sensitive values.

```php
'connections' => [
    'secure' => [
        'host' => 'mqtt.example.com',
        'port' => 8883,
        'protocol' => \PhpMqtt\Client\MqttClient::MQTT_3_1,
        'client_id' => env('MQTT_CLIENT_ID'),
        'use_clean_session' => true,
        'enable_logging' => true,
        'log_channel' => 'mqtt',
        'repository' => \PhpMqtt\Client\Repositories\MemoryRepository::class,
        'connection_settings' => [
            'connect_timeout' => 60,
            'socket_timeout' => 5,
            'resend_timeout' => 10,
            'keep_alive_interval' => 10,
            'auth' => [
                'username' => env('MQTT_AUTH_USERNAME'),
                'password' => env('MQTT_AUTH_PASSWORD'),
            ],
            'tls' => [
                'enabled' => true,
                'allow_self_signed_certificate' => false,
                'verify_peer' => true,
                'verify_peer_name' => true,
                'ca_file' => env('MQTT_TLS_CA_FILE'),
            ],
            'last_will' => [
                'topic' => 'clients/offline',
                'message' => 'client disconnected',
                'quality_of_service' => 0,
                'retain' => false,
            ],
            'auto_reconnect' => [
                'enabled' => true,
                'max_reconnect_attempts' => 3,
                'delay_between_reconnect_attempts' => 5,
            ],
        ],
    ],
],
```

--------------------------------

### publish() method signature with docblock

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Exact signature of ConnectionManager::publish() from src/ConnectionManager.php:109. Publishes a message with QoS 0, optional retain flag, and optional connection name. Throws BindingResolutionException, ConfigurationInvalidException, ConnectingToBrokerFailedException, ConnectionNotAvailableException, DataTransferException, ProtocolNotSupportedException, and RepositoryException.

```php
/**
 * Publishes a message on the given connection. The QoS level will be 0.
 *
 * @param string      $topic
 * @param string      $message
 * @param bool        $retain
 * @param string|null $connection
 * @throws BindingResolutionException
 * @throws ConfigurationInvalidException
 * @throws ConnectingToBrokerFailedException
 * @throws ConnectionNotAvailableException
 * @throws DataTransferException
 * @throws ProtocolNotSupportedException
 * @throws RepositoryException
 */
public function publish(string $topic, string $message, bool $retain = false, ?string $connection = null): void
```

--------------------------------

### Exit loop with second parameter

Source: https://github.com/php-mqtt/laravel-client/blob/master/README.md

Passes true as second parameter to loop() to exit as soon as all resend queues are cleared.

```php
/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
$mqtt->loop(true, true);
```

--------------------------------

### subscribe

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/types.md

Subscribes to a topic with a callback function and a QoS level. The callback receives the topic and message as arguments.

```APIDOC
## subscribe

### Description
Subscribes to a topic with a callback function and a QoS level. The callback receives the topic and message as arguments.

### Method
subscribe

### Signature
`subscribe($topic, $callback, $qos)`

### Parameters
- **$topic** (string) - Required - The topic to subscribe to.
- **$callback** (callable) - Required - A callback function `function (string $topic, string $message)`.
- **$qos** (int) - Required - QoS level (0, 1, or 2).

### Usage Example
```php
$mqtt->subscribe('some/topic', function (string $topic, string $message) {
    // handle message
}, 1);
```
```

--------------------------------

### Disconnect after explicit loop-based publish (QoS 1)

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Shows using MQTT::connection() to publish with QoS 1, running the loop until resend queues are cleared, then manually releasing the connection with MQTT::disconnect().

```php
use PhpMqtt\Client\Facades\MQTT;

$mqtt = MQTT::connection();
$mqtt->publish('some/topic', 'foo', 1);       // QoS 1 requires the loop for the ack
$mqtt->loop(true, true);                      // exit loop once resend queues are cleared
MQTT::disconnect();                           // release the connection manually
```

--------------------------------

### MQTT::publish()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Publishes a message to an MQTT topic with QoS level 0. This is a one-off operation that opens the connection implicitly but does not close it; use MQTT::disconnect() to close it later.

```APIDOC
## [STATIC] MQTT::publish()

### Description
Publishes a message to an MQTT topic with QoS level 0. This is a one-off operation that opens the connection implicitly but does not close it; use MQTT::disconnect() to close it later.

### Method
Static method on the MQTT facade

### Signature
```php
@method static void publish(string $topic, string $message, bool $retain = false, string|null $connection = null)
```

### Parameters
- **$topic** (string) - Required - The MQTT topic to publish to.
- **$message** (string) - Required - The payload to publish.
- **$retain** (bool) - Optional - Default: `false` - Whether the broker shall retain the message.
- **$connection** (string|null) - Optional - Default: `null` - Connection name to use; `null` resolves to the `default_connection`.

### Returns
- **void**

### Throws
- `BindingResolutionException`
- `ConfigurationInvalidException`
- `ConnectingToBrokerFailedException`
- `ConnectionNotAvailableException`
- `DataTransferException`
- `ProtocolNotSupportedException`
- `RepositoryException`

### Behavior
- Always publishes with QoS level 0 (`MqttClient::QOS_AT_MOST_ONCE`).
- One-off operation; no event loop is run.
- Connection is opened implicitly and not closed afterwards — close it later with `MQTT::disconnect()` if needed.
- For QoS 1/2, use `$mqtt = MQTT::connection()` and call `publish()`/`loop()` on the client directly.

### Example — basic usage
```php
use PhpMqtt\Client\Facades\MQTT;

// Publish with QoS 0, retain = false, default connection:
MQTT::publish('some/topic', 'Hello World!');

// Publish with the retain flag and an explicit connection:
MQTT::publish('some/topic', 'Hello World!', true, 'public');
```

### Example — error handling in a request context
```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\DataTransferException;

try {
    MQTT::publish('alerts/server-down', $message, true, 'private');
} catch (ConnectionNotAvailableException $e) {
    Log::error('MQTT connection not configured: ' . $e->getMessage());
} catch (DataTransferException $e) {
    // e.g. publish failed while transferring data to the broker
    Log::error('MQTT publish failed: ' . $e->getMessage());
}
```
```

--------------------------------

### ConnectionManager constructor signature

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Constructor for ConnectionManager, stores the Laravel application and mqtt-client config. Not called directly; resolve via app(ConnectionManager::class).

```php
/**
 * ConnectionManager constructor.
 *
 * @param Application $application
 * @param array       $config
 */
public function __construct(Application $application, array $config)
```

--------------------------------

### Error handling: missing connection and broker unreachable

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Catches ConnectionNotAvailableException for a missing connection name and ConnectingToBrokerFailedException when the broker cannot be reached.

```php
use PhpMqtt\Client\ConnectionManager;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;
use PhpMqtt\Client\Exceptions\ConnectingToBrokerFailedException;

$manager = app(ConnectionManager::class);

try {
    $client = $manager->connection('missing');
} catch (ConnectionNotAvailableException $e) {
    // 'missing' is not a key in config('mqtt-client.connections')
} catch (ConnectingToBrokerFailedException $e) {
    // host/port from the config could not be connected
}
```

--------------------------------

### Catch BindingResolutionException when publishing via MQTT facade

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/errors.md

Wrap MQTT::publish() in a try/catch for BindingResolutionException, which occurs when the container cannot resolve the configured repository class or the 'log' binding in ConnectionManager::createConnection(). The exception surfaces through connection(), createConnection(), and publish() methods and their MQTT facade equivalents.

```php
use PhpMqtt\Client\Facades\MQTT;
use Illuminate\Contracts\Container\BindingResolutionException;

try {
    MQTT::publish('some/topic', 'payload');
} catch (BindingResolutionException $e) {
    // e.g. a custom repository class configured that is not bound/autowirable
    report($e);
}
```

--------------------------------

### Catch MQTT exceptions with MqttClientException

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/errors.md

Use this try-catch block in consumer code to handle all MQTT-specific failures (e.g., ConnectionNotAvailableException, ConfigurationInvalidException) via the base MqttClientException, with a fallback for non-MQTT errors. The catch-all is safe regardless of whether MqttClientException extends \Exception or \RuntimeException.

```php
use PhpMqtt\Client\Exceptions\MqttClientException; // base class of this package's exceptions (external)

try {
    $mqtt = MQTT::connection();
    $mqtt->publish('some/topic', 'foo', 1);
    $mqtt->loop(true, true);
} catch (MqttClientException $e) {
    // All MQTT-specific failures in one catch: ConnectionNotAvailableException,
    // ConfigurationInvalidException, ConnectingToBrokerFailedException,
    // DataTransferException, ProtocolNotSupportedException, RepositoryException
    report($e);
} catch (\Throwable $e) {
    // Fallback for non-MQTT failures (binding resolution, ...)
    report($e);
}
```

--------------------------------

### __construct(Application $application, array $config)

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Constructor for the ConnectionManager class. Stores the application and config, and computes the default connection name. In normal usage, resolve the class from the container instead of calling this directly.

```APIDOC
## __construct(Application $application, array $config)

### Description
Constructor for the ConnectionManager class. Stores the application and config, and computes the default connection name. In normal usage, resolve the class from the container instead of calling this directly.

### Method
Constructor

### Signature
```php
public function __construct(Application $application, array $config)
```

### Parameters
- **$application** (Illuminate\Contracts\Foundation\Application) - Required - Laravel application instance; used to resolve repositories and loggers from the container.
- **$config** (array) - Required - The `mqtt-client` config array (as returned by `config('mqtt-client')`).

### Returns
- **ConnectionManager** instance.

### Behavior
- Stores the application and config, and computes `$defaultConnection = Arr::get($config, 'default_connection', 'default')` — i.e. the fallback default connection name is `'default'` if the config key is absent.
- In normal usage this constructor is not called by application code; resolve the class from the container: `app(ConnectionManager::class)` (which yields the `$app->make('config')->get('mqtt-client', [])` config per the provider binding).
```

--------------------------------

### MQTT::publish

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Publishes a message to an MQTT topic. This static facade method forwards to the ConnectionManager's publish method to send a message on the specified connection.

```APIDOC
## MQTT::publish

### Description
Publishes a message to an MQTT topic. This static facade method forwards to the ConnectionManager's publish method to send a message on the specified connection.

### Method
publish

### Signature
`MQTT::publish(string $topic, string $message, bool $retain = false, string|null $connection = null)`

### Parameters
- **$topic** (string) - Required - The topic to publish to.
- **$message** (string) - Required - The message payload.
- **$retain** (bool) - Optional - Whether to retain the message. Defaults to false.
- **$connection** (string|null) - Optional - The connection name. If null, the default connection is used.

### Return Value
- **void** - No return value.
```

--------------------------------

### ConnectionManager class skeleton with constructor

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Shows the class declaration and constructor for ConnectionManager. The constructor stores the application container and configuration, and sets the default connection name from the 'default_connection' config key, defaulting to 'default'.

```php
/**
 * Manages the MQTT connections of the application.
 *
 * @package PhpMqtt\Client
 */
class ConnectionManager
{
    private Application $application;
    private array $config;
    private string $defaultConnection;

    /** @var MqttClientContract[] */
    private array $connections = [];

    /**
     * ConnectionManager constructor.
     *
     * @param Application $application
     * @param array       $config
     */
    public function __construct(Application $application, array $config)
    {
        $this->application       = $application;
        $this->config            = $config;
        $this->defaultConnection = Arr::get($config, 'default_connection', 'default');
    }
}
```

--------------------------------

### __construct(string $name)

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionNotAvailableException.md

Constructor for the ConnectionNotAvailableException class. It creates an exception instance with a message indicating that the specified MQTT connection name could not be found.

```APIDOC
## __construct(string $name)

### Description
Creates a new ConnectionNotAvailableException instance. The exception message includes the provided connection name.

### Method
Constructor

### Parameters
- **$name** (string) - Required - The connection name that could not be resolved; embedded in the exception message.

### Returns
Exception instance (constructor, never returns a value).

### Message Format
`An MQTT connection with the name [<name>] could not be found.`

### Example
```php
use PhpMqtt\Client\Facades\MQTT;
use PhpMqtt\Client\Exceptions\ConnectionNotAvailableException;

try {
    $mqtt = MQTT::connection('not-configured');
} catch (ConnectionNotAvailableException $e) {
    // $e->getMessage() === 'An MQTT connection with the name [not-configured] could not be found.'
    Log::error('MQTT connection missing: ' . $e->getMessage());
}
```
```

--------------------------------

### Full source of ConnectionNotAvailableException class

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionNotAvailableException.md

The complete class definition for ConnectionNotAvailableException, extending MqttClientException. The constructor formats the exception message with the connection name.

```php
<?php

declare(strict_types=1);

namespace PhpMqtt\Client\Exceptions;

/**
 * Class ConnectionNotAvailableException
 *
 * @package PhpMqtt\Client\Exceptions
 */
class ConnectionNotAvailableException extends MqttClientException
{
    public function __construct(string $name)
    {
        parent::__construct(sprintf('An MQTT connection with the name [%s] could not be found.', $name));
    }
}
```

--------------------------------

### Basic usage of disconnect()

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/ConnectionManager.md

Shows how to close the default connection explicitly after publishing a message. The default connection is opened implicitly by MQTT::publish().

```php
use PhpMqtt\Client\ConnectionManager;

$manager = app(ConnectionManager::class);

MQTT::publish('some/topic', 'Hello World!');  // opens the default connection implicitly
$manager->disconnect();                       // now close it explicitly
```

--------------------------------

### Manual service provider registration

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MqttClientServiceProvider.md

Add MqttClientServiceProvider to the providers array when auto-discovery is disabled. Use bootstrap/providers.php for Laravel 11+ or config/app.php 'providers' for Laravel 10.

```php
// bootstrap/providers.php (Laravel 11+) or config/app.php 'providers' (Laravel 10)
return [
    App\Providers\AppServiceProvider::class,
    PhpMqtt\Client\MqttClientServiceProvider::class,
];
```

--------------------------------

### MQTT::disconnect() signature annotation

Source: https://github.com/php-mqtt/laravel-client/blob/master/_autodocs/api-reference/MQTT.md

Exact @method annotation from the facade, declaring the static disconnect() method with an optional connection name parameter.

```php
@method static void disconnect(string|null $connection = null)
```
Tokens:
Raw