PHPackages                             ultraembeddedlab/php-iot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. ultraembeddedlab/php-iot

ActiveLibrary[HTTP & Networking](/categories/http)

ultraembeddedlab/php-iot
========================

Modern, production-grade MQTT 3.1.1 & 5 client for PHP 8.4+

v1.3.0(3mo ago)0189MITPHPPHP ^8.4CI passing

Since Jan 18Pushed 3mo agoCompare

[ Source](https://github.com/UltraEmbeddedLab/php-iot)[ Packagist](https://packagist.org/packages/ultraembeddedlab/php-iot)[ Docs](https://github.com/UltraEmbeddedLab/php-iot)[ RSS](/packages/ultraembeddedlab-php-iot/feed)WikiDiscussions main Synced today

READMEChangelog (4)Dependencies (18)Versions (5)Used By (0)

PHP IoT MQTT Client
===================

[](#php-iot-mqtt-client)

[![CI](https://github.com/UltraEmbeddedLab/php-iot/actions/workflows/ci.yml/badge.svg)](https://github.com/UltraEmbeddedLab/php-iot/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/9009b8b6038634eef7f34c2437b2730b9a879c559c11dea31a7edbf76b669fce/68747470733a2f2f706f7365722e707567782e6f72672f756c747261656d6265646465646c61622f7068702d696f742f76)](https://packagist.org/packages/ultraembeddedlab/php-iot)[![License](https://camo.githubusercontent.com/aaf5e5866bf4434730790fb3cac35eb09df43b4fc58f0197ddef3ed487524797/68747470733a2f2f706f7365722e707567782e6f72672f756c747261656d6265646465646c61622f7068702d696f742f6c6963656e7365)](https://packagist.org/packages/ultraembeddedlab/php-iot)[![PHP Version](https://camo.githubusercontent.com/82fc31d92b701f19ffbb1928418af4a84ce56c93e2d65384dd928fbbd7e043a4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f756c747261656d6265646465646c61622f7068702d696f74)](https://packagist.org/packages/ultraembeddedlab/php-iot)

Modern, production-grade MQTT 3.1.1 & 5.0 client for PHP 8.4+

Features
--------

[](#features)

- **Modern PHP 8.4+** with strict types and modern syntax
- **MQTT 3.1.1 & 5.0** protocol support
- **TLS/SSL & mutual TLS (mTLS)** with typed `TlsOptions` — client certificates, CA verification, ALPN
- **WebSocket transport** (`ws://`, `wss://`) with RFC 6455 framing
- **Auto-reconnect** with exponential backoff and jitter
- **QoS 0, 1, 2** with automatic resend on ACK timeout
- **Session persistence** for reliable message delivery
- **Rate limiter** (token bucket) to prevent broker flooding
- **Offline message queue** with automatic drain on reconnect
- **Topic aliases** (MQTT 5.0)
- **Flow control** (MQTT 5.0)
- **Shared subscriptions** (MQTT 5.0)
- **Byte counters** for traffic monitoring (`bytesSent()` / `bytesReceived()`)
- **PSR-3** logging support
- **PSR-14** event dispatcher support

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- `ext-sockets` extension
- `ext-openssl` extension (for TLS)

Installation
------------

[](#installation)

Install via Composer:

```
composer require ultraembeddedlab/php-iot
```

Quick Start
-----------

[](#quick-start)

### Simple Publish (Fire and Forget)

[](#simple-publish-fire-and-forget)

The easiest way to publish a message:

```
use ScienceStories\Mqtt\Easy\Mqtt;

Mqtt::publish(
    host: 'broker.example.com',
    topic: 'sensors/temperature',
    payload: '23.5',
);
```

### Publish with TLS and Authentication

[](#publish-with-tls-and-authentication)

```
use ScienceStories\Mqtt\Easy\Mqtt;

Mqtt::publish(
    host: 'broker.example.com',
    topic: 'sensors/temperature',
    payload: '23.5',
    tls: true,
    username: 'user',
    password: 'secret',
);
```

### Using MQTT 5.0

[](#using-mqtt-50)

```
use ScienceStories\Mqtt\Easy\Mqtt;
use ScienceStories\Mqtt\Protocol\QoS;

Mqtt::publish(
    host: 'broker.example.com',
    topic: 'sensors/temperature',
    payload: '23.5',
    version: 'v5',
    qos: QoS::AtLeastOnce,
    properties: [
        'message_expiry_interval' => 3600,
        'content_type' => 'text/plain',
    ],
);
```

### Subscribe to Topics

[](#subscribe-to-topics)

For more complex use cases, use the full client:

```
use ScienceStories\Mqtt\Client\Client;
use ScienceStories\Mqtt\Client\Options;
use ScienceStories\Mqtt\Protocol\MqttVersion;
use ScienceStories\Mqtt\Transport\TcpTransport;

$options = new Options(
    host: 'broker.example.com',
    port: 1883,
    version: MqttVersion::V5_0,
);

$options = $options
    ->withClientId('my-client')
    ->withKeepAlive(60)
    ->withCleanSession(true);

$client = new Client($options, new TcpTransport());
$client->connect();

// Subscribe to topics
$client->subscribe([
    ['filter' => 'sensors/#', 'qos' => 1],
]);

// Handle incoming messages
$client->onMessage(function ($message) {
    echo "Received: {$message->payload} on {$message->topic}\n";
});

// Listen for messages
while (true) {
    $client->loopOnce(1.0);
}
```

### Long-Running Connection

[](#long-running-connection)

Use the `Mqtt::connect()` method for sessions that need to publish multiple messages:

```
use ScienceStories\Mqtt\Easy\Mqtt;
use ScienceStories\Mqtt\Client\PublishOptions;
use ScienceStories\Mqtt\Protocol\QoS;

$client = Mqtt::connect(
    host: 'broker.example.com',
    port: 1883,
    version: 'v5',
);

// Publish multiple messages
$client->publish('sensors/temp', '23.5', new PublishOptions(qos: QoS::AtLeastOnce));
$client->publish('sensors/humidity', '65', new PublishOptions(qos: QoS::AtLeastOnce));

$client->disconnect();
```

Configuration Options
---------------------

[](#configuration-options)

### Client Options

[](#client-options)

OptionTypeDefaultDescription`host`stringrequiredMQTT broker hostname`port`int1883/8883Broker port (auto-detected based on TLS)`version`MqttVersionV3\_1\_1MQTT protocol version`clientId`stringautoClient identifier`keepAlive`int60Keep alive interval in seconds`cleanSession`booltrueStart with clean session`username`stringnullAuthentication username`password`stringnullAuthentication password`ackTimeout`float5.0Timeout (seconds) waiting for QoS 1/2 ACK before resend`maxResendAttempts`int3Max resend attempts for unacknowledged QoS 1/2 messages### Publish Options

[](#publish-options)

OptionTypeDefaultDescription`qos`QoSAtMostOnceQuality of Service level`retain`boolfalseRetain message on broker`properties`arraynullMQTT 5.0 properties### TLS Configuration

[](#tls-configuration)

Simple TLS (server verification only):

```
use ScienceStories\Mqtt\Client\TlsOptions;

$options = $options->withTls(new TlsOptions());
```

Mutual TLS with client certificate (AWS IoT, Azure IoT Hub):

```
use ScienceStories\Mqtt\Client\TlsOptions;

$tls = (new TlsOptions())
    ->withCaFile('/etc/mqtt/certs/ca.pem')
    ->withClientCertificate(
        certFile: '/etc/mqtt/certs/client.pem',
        keyFile: '/etc/mqtt/certs/client.key',
        passphrase: 'optional-passphrase',
    );

$options = $options->withTls($tls);
```

MQTT over port 443 with ALPN (when 8883 is blocked):

```
$tls = (new TlsOptions())
    ->withCaFile('/etc/mqtt/certs/ca.pem')
    ->withClientCertificate('/etc/mqtt/certs/client.pem', '/etc/mqtt/certs/client.key')
    ->withAlpn('mqtt');

$options = (new Options('broker.example.com', 443))->withTls($tls);
```

Self-signed certificates (development):

```
$tls = (new TlsOptions())
    ->withCaFile('/path/to/my-ca.pem')
    ->withAllowSelfSigned(true);

$options = $options->withTls($tls);
```

TlsOptions MethodDescription`withCaFile(?string)`CA certificate file for server verification`withCaPath(?string)`Directory of CA certificates`withClientCertificate(?string, ?string, ?string)`Client cert, key, and optional passphrase`withAlpn(?string)`ALPN protocol (e.g., `'mqtt'` for port 443)`withVerifyPeer(bool)`Verify server certificate (default: `true`)`withVerifyPeerName(bool)`Verify server hostname (default: `true`)`withAllowSelfSigned(bool)`Allow self-signed certs (default: `false`)`withPeerName(?string)`Override peer name for SNI`withSni(bool)`Enable/disable SNI (default: `true`)> Legacy `array` syntax is still supported for backward compatibility: `$options->withTls(['ssl' => ['verify_peer' => true]])`

MQTT 5.0 Features
-----------------

[](#mqtt-50-features)

### Topic Aliases

[](#topic-aliases)

Reduce bandwidth by using numeric aliases for frequently used topics:

```
$client->publish('long/topic/name', 'data', new PublishOptions(
    properties: ['topic_alias' => 1],
));
```

### Message Expiry

[](#message-expiry)

Set expiration time for messages:

```
$client->publish('alerts/warning', 'Alert!', new PublishOptions(
    properties: ['message_expiry_interval' => 300], // 5 minutes
));
```

### User Properties

[](#user-properties)

Attach custom metadata to messages:

```
$client->publish('events/user', $payload, new PublishOptions(
    properties: [
        'user_properties' => [
            'source' => 'web-app',
            'version' => '1.0',
        ],
    ],
));
```

Documentation
-------------

[](#documentation)

Detailed documentation is available in the `docs/` directory:

- [Flow Control](docs/flow-control.md)
- [Session Persistence](docs/session-persistence.md)
- [Shared Subscriptions](docs/shared-subscriptions.md)
- [Topic Aliases](docs/topic-aliases.md)
- [Server Disconnect](docs/server-disconnect.md)

Examples
--------

[](#examples)

Check the `examples/` directory for complete working examples:

- Basic connect/publish/subscribe (MQTT 3.1.1 and 5.0)
- QoS 0, 1, 2 demonstrations
- **mTLS with client certificates** (`tls_mtls_example.php` + cert generation script)
- Session persistence, shared subscriptions, topic aliases
- Flow control, server disconnect handling

Testing
-------

[](#testing)

```
# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Static analysis
composer stan

# Code style
composer pint
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

License
-------

[](#license)

PHP IoT MQTT Client is open-sourced software licensed under the [MIT license](LICENSE.md).

Credits
-------

[](#credits)

Developed by [Bogdan Gewald](mailto:gewaldb@gmail.com)

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance82

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~25 days

Total

4

Last Release

91d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/105855972?v=4)[Science Stories](/maintainers/science-stories)[@Science-Stories](https://github.com/Science-Stories)

---

Top Contributors

[![electronic-club](https://avatars.githubusercontent.com/u/87986804?v=4)](https://github.com/electronic-club "electronic-club (20 commits)")

---

Tags

laravelmqttphpclientiotmqttpub-subnetworkingphp84message-brokermqtt3mqtt5

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ultraembeddedlab-php-iot/health.svg)

```
[![Health](https://phpackages.com/badges/ultraembeddedlab-php-iot/health.svg)](https://phpackages.com/packages/ultraembeddedlab-php-iot)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[symfony/http-kernel

Provides a structured process for converting a Request into a Response

8.1k869.4M8.8k](/packages/symfony-http-kernel)[symfony/mailer

Helps sending emails

1.6k409.1M1.4k](/packages/symfony-mailer)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M421](/packages/drupal-core-recommended)[web-auth/webauthn-lib

FIDO2/Webauthn Support For PHP

12310.5M135](/packages/web-auth-webauthn-lib)[php-mqtt/client

An MQTT client written in and for PHP.

4542.4M36](/packages/php-mqtt-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)