Download the PHP package ultraembeddedlab/php-iot without Composer

PHP IoT MQTT Client

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

Features

• Modern PHP 8.4+ with strict types and modern syntax
• MQTT 3.1.1 & 5.0 protocol support
• TLS 1.2+ & mutual TLS (mTLS) — TLS 1.0/1.1 refused by default (RFC 8996); typed TlsOptions for client certificates, CA verification and ALPN
• WebSocket transport (ws://) with RFC 6455 framing — wss:// is not functional yet, see Known Limitations
• 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

• PHP 8.4 or higher
• ext-json (bundled with PHP and not removable since 8.0)
• ext-openssl — only for TLS (mqtts://, wss://). Plain TCP works without it.

No other extensions are needed: all I/O goes through PHP's stream functions.

Installation

Install via Composer:

Upgrading from ultraembeddedlab/php-iot 1.x? The package was renamed in 2.0 — the PHP namespace is unchanged, so no use statement moves. See UPGRADE.md.

Quick Start

Simple Publish (Fire and Forget)

The easiest way to publish a message:

Publish with TLS and Authentication

Using MQTT 5.0

Subscribe to Topics

For more complex use cases, use the full client:

Long-Running Connection

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

Configuration Options

Client Options

Publish Options

TLS Configuration

Simple TLS (server verification only):

withHost('other-broker') resets the port to 1883. When changing host on an existing Options, pass both: withHost('other-broker', 8883).

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

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

Self-signed certificates (development):

TLS 1.2 and 1.3 only, by default. PHP's own STREAM_CRYPTO_METHOD_TLS_CLIENT still enables TLS 1.0 and 1.1, which RFC 8996 marks MUST NOT and PCI-DSS prohibits. This client refuses them unless you widen the policy explicitly:

Legacy array syntax is still supported for backward compatibility: $options->withTls(['ssl' => ['verify_peer' => true]])

MQTT 5.0 Features

Topic Aliases

Topic aliases replace a repeated topic string with a two-byte integer. They are managed automatically — request a budget on Options, then publish normally:

The broker's topic_alias_maximum in CONNACK overrides your request; if it advertises 0, aliasing is disabled and publishes fall back to full topic strings.

Do not set the topic_alias property by hand on PublishOptions. Aliases are connection-scoped and negotiated — a hand-set value is either overwritten by the client or rejected by the broker with reason code 0x94 (Topic Alias Invalid).

Message Expiry

Set expiration time for messages:

User Properties

Attach custom metadata to messages:

Error Handling

Every error this library raises extends ScienceStories\Mqtt\Exception\MqttException, which extends RuntimeException — so a single catch covers the whole surface.

connect() throws rather than returning a failed result, so a refused connection cannot be mistaken for a live one:

A long-running loop should survive transient failures rather than dying on the first one:

With withAutoReconnect() enabled, loopOnce() re-establishes the connection and re-subscribes on its own; it returns false while disconnected rather than throwing.

Known Limitations

Stated up front rather than discovered in production:

• wss:// does not work. WsTransport performs the HTTP upgrade before TLS can be enabled, so only ws:// completes a handshake. ws:// itself has no test coverage yet.
• Inbound MQTT 5 topic aliases are not resolved. If a broker sends aliased PUBLISH packets, the topic arrives empty. Leave withTopicAliasMaximum() at 0 (the default).
• Acknowledgement reason codes are not acted on. A PUBACK or SUBACK carrying a failure code is logged, not raised — a rejected subscription looks successful.
• The client is blocking. There is no ReactPHP/Amp adapter yet; run it in a dedicated process or worker.
• No Laravel or Symfony bridge yet.

See CHANGELOG.md for what changed and what is planned.

Documentation

• Upgrading from 1.x — what changed in 2.0 and how to migrate
• Backward Compatibility Promise — what semver covers here
• Roadmap — what is planned, and where help is wanted

Feature guides in docs/:

• Testing — unit-test your MQTT code with InMemoryTransport, no broker needed
• Flow Control — MQTT 5 receive-maximum and in-flight limits
• Session Persistence — surviving restarts with cleanSession: false
• Shared Subscriptions — $share/ load balancing across consumers
• Topic Aliases — MQTT 5 bandwidth optimisation
• Server Disconnect — reacting to a broker-initiated DISCONNECT

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

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

PHP IoT MQTT Client is open-sourced software licensed under the MIT license.

Credits

Developed by Bogdan Gewald.

UltraEmbeddedLab is the publishing organisation for this package; copyright is held by Bogdan Gewald, as stated in LICENSE.md. Contributions are accepted under the Developer Certificate of Origin — inbound licence equals outbound licence, MIT. There is no copyright assignment and no CLA.

The PHP namespace is ScienceStories\Mqtt\ for historical reasons: the package was originally published as science-stories/php-iot. It is unchanged for backwards compatibility and is scheduled to be renamed in 3.0 with class_alias() shims — see ROADMAP.md.