Mqtt Laravel Package

Technical Evaluation

Architecture fit

• simps/mqtt is a protocol-level MQTT client, not a framework integration. It belongs at the messaging edge of the architecture — device telemetry ingest, command dispatch, IoT/event fan-out — and should be isolated behind an internal interface rather than called directly from controllers.
• The library targets coroutine runtimes (Swoole, with Swow support in the broader simps ecosystem), which is a fundamental mismatch with stock Laravel on PHP-FPM. It only fits cleanly in one of two shapes: (a) a Laravel Octane deployment running on Swoole, or (b) dedicated long-running worker processes decoupled from the HTTP tier.
• The cleanest architecture is publish-through-queue and subscribe-through-daemon: HTTP requests enqueue jobs, a worker publishes, a supervised consumer daemon subscribes and dispatches back into Laravel's event/queue system.

Integration feasibility

• Composer-installable, PSR-4, Apache-2.0, no framework lock-in. Integration surface is small and well-bounded.
• Hard environmental gate: ext-swoole (or Swow) must be present and permitted in the hosting environment. Containerized deploys are fine; some managed PHP platforms are not.
• No first-party Laravel service provider, facade, or config publishing. Expect to write a thin provider (~100–200 LOC) yourself, or vet a community wrapper.

Technical risk

• Runtime coupling to Swoole/Swow is the dominant risk — it constrains hosting choices and forces every developer touching the integration to understand the coroutine lifecycle.
• Ecosystem maturity: 397 stars is credible for a protocol client but small relative to production messaging surface area; bus factor and long-term maintenance should be treated as real.
• Protocol correctness risk is concentrated in MQTT 5.0 (properties, shared subscriptions, topic aliases, reason codes). Treat 3.1.1 as the proven baseline and validate each 5.0 feature you intend to use.
• Operational semantics — reconnect/backoff, session persistence, will messages, dead-lettering, TLS session resumption — are typically the consumer's responsibility, not the library's. Budget for this explicitly.
• No built-in metrics/tracing hooks; observability must be instrumented by you.

Key questions

• Which QoS levels and session modes are proven in production use, and at what scale?
• Does the library handle reconnect and backoff, or must the application implement them?
• Which runtime is targeted in practice — Swoole, Swow, or both — and which will we operate?
• Is mTLS (client certs, custom CA) supported and tested?
• Which brokers are validated (Mosquitto, EMQX, HiveMQ, AWS IoT Core)?
• What is the maintainer team size, release cadence, and security disclosure process?

Integration Approach

Stack fit

• Laravel 10/11 + Octane(Swoole) if in-request publishing is genuinely required; otherwise a standalone worker container is simpler and safer.
• Publishing should go through queued jobs so retries, backoff, and failure accounting are owned by Laravel's queue rather than a socket.
• Broker credentials via config + secrets manager; never in code or .env committed to VCS.
• Keep the HTTP request path free of MQTT wherever possible — one slow broker should not slow a user-facing request.

Migration path

• Phase 0 — spike: connect, publish, subscribe against the real target broker with real TLS config in a scratch artisan command.
• Phase 1 — publish-only from a single bounded context (e.g., device commands), behind an MqttPublisher interface so the implementation can be swapped.
• Phase 2 — subscriber daemon for one topic tree, dispatching decoded messages into jobs/events.
• Phase 3 — hardening: reconnect strategy, dead-letter handling, metrics, alerting, load test.

Compatibility

• PHP 8.1+, ext-swoole 5.x or Swow. Confirm against your base image before committing.
• Brokers: validate on 3.1.1 first as the lowest common denominator; opt into 5.0 features per broker with explicit tests.
• Do not co-locate blocking I/O in the same process; any synchronous call stalls the entire event loop and silently degrades throughput.

Sequencing Interface abstraction → PoC on target broker → publish path → consumer daemon → observability → scale-out. Each phase should be independently shippable and reversible.

Operational Impact

Maintenance

• Pin exact versions and upgrade deliberately; the maintainer base is small enough that a breaking change or abandonment is a plausible scenario.
• Apache-2.0 (permissive, patent grant) is commercially safe; no copyleft exposure.
• Assume you own the wrapper layer, reconnect logic, and any Laravel-idiomatic ergonomics.

Support

• Community-only: no vendor SLA, no paid escalation. Issues/PRs upstream are the only path. Keep the option of a private fork and be prepared to patch.
• Document an internal owner for the integration; it is infrastructure, not a feature someone picks up ad hoc.

Scaling

• One connection can carry many subscriptions; scale out by adding consumer instances (preferably via broker shared subscriptions), not by multiplying connections per process.
• Long-lived workers need a restart policy (max-messages/max-requests equivalent) to bound memory growth.
• Monitor per-connection throughput, coroutine count, and event-loop lag; these are the leading indicators of saturation.

Failure modes

• Silent reconnect loops and broker failover producing gaps in message delivery.
• Backpressure when handlers are slower than inbound rate — unbounded coroutine growth and OOM rather than clean shedding.
• QoS 1 duplicate delivery — handlers must be idempotent; QoS 0 loss is by design and must be acceptable to the use case.
• Blocking code in a consumer stalls the entire worker, not just one message.
• Memory growth in long-running processes; TLS handshake failures after certificate rotation.

Ramp-up

• Mid-level PHP developers need roughly 1–2 weeks to become productive with the Swoole/coroutine model, plus about a week for MQTT semantics (QoS, retained messages, sessions, topic design).
• Ops needs to learn supervisor/container lifecycle for daemons and broker-side monitoring and alerting.
• Write an ADR capturing the runtime decision, the broker contract, and the reconnect/backoff policy before Phase 1 ships.