PHPackages nashgao/mqtt - 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. nashgao/mqtt ActiveLibrary[HTTP & Networking](/categories/http) nashgao/mqtt ============ encapsulation of mqtt client based on simps mqtt v0.2.1(4mo ago)3993↓54.8%1[2 issues](https://github.com/nashgao/mqtt-client/issues)[1 PRs](https://github.com/nashgao/mqtt-client/pulls)MITPHPPHP >=8.3CI passing Since May 2Pushed 3mo ago1 watchersCompare [ Source](https://github.com/nashgao/mqtt-client)[ Packagist](https://packagist.org/packages/nashgao/mqtt)[ RSS](/packages/nashgao-mqtt/feed)WikiDiscussions master Synced yesterday READMEChangelog (10)Dependencies (32)Versions (25)Used By (0) Nashgao/MQTT ============ [](#nashgaomqtt) A PHP MQTT client library for Hyperf framework with MQTT 5 shared subscription support. [![Latest Stable Version](https://camo.githubusercontent.com/f34416982acb224bae53b0fb4fa1f9f87a8c7ab863352747423ef84526b19bbc/687474703a2f2f706f7365722e707567782e6f72672f6e61736867616f2f6d7174742f76)](https://packagist.org/packages/nashgao/mqtt)[![Total Downloads](https://camo.githubusercontent.com/9e8eba865374ebca69d3bc00ce91e6a0d57cedee51e8c8336841f37c3639df16/687474703a2f2f706f7365722e707567782e6f72672f6e61736867616f2f6d7174742f646f776e6c6f616473)](https://packagist.org/packages/nashgao/mqtt)[![Latest Unstable Version](https://camo.githubusercontent.com/5cf1f16fc84e0ca6d9b8fa4e5e6b1fd9929d62eabe71b7eab742dd071d77efeb/687474703a2f2f706f7365722e707567782e6f72672f6e61736867616f2f6d7174742f762f756e737461626c65)](https://packagist.org/packages/nashgao/mqtt)[![License](https://camo.githubusercontent.com/20d3c75ff27f0a398085502d618676cf0be7c70b722e3945baaf24e4fba5a03a/687474703a2f2f706f7365722e707567782e6f72672f6e61736867616f2f6d7174742f6c6963656e7365)](https://packagist.org/packages/nashgao/mqtt)[![PHP Version Require](https://camo.githubusercontent.com/ba893900f777996de7e8d532844a14c16fb1975d795e3278a35e143c1a66803b/687474703a2f2f706f7365722e707567782e6f72672f6e61736867616f2f6d7174742f726571756972652f706870)](https://packagist.org/packages/nashgao/mqtt) Installation ------------ [](#installation) ``` composer require nashgao/mqtt ``` Publish the configuration file: ``` php bin/hyperf.php vendor:publish nashgao/mqtt ``` Quick Start ----------- [](#quick-start) ### Publishing Messages [](#publishing-messages) ``` use Nashgao\MQTT\Event\PublishEvent; use Psr\EventDispatcher\EventDispatcherInterface; $dispatcher = ApplicationContext::getContainer()->get(EventDispatcherInterface::class); $dispatcher->dispatch(new PublishEvent('topic/test', 'Hello MQTT!', 2)); ``` ### Subscribing to Topics [](#subscribing-to-topics) ``` use Nashgao\MQTT\Event\SubscribeEvent; use Nashgao\MQTT\Config\TopicConfig; $event = new SubscribeEvent(topicConfigs: [ new TopicConfig(['topic' => 'topic/test', 'qos' => 2]) ]); $dispatcher->dispatch($event); ``` Project Overview ---------------- [](#project-overview) **Nashgao/MQTT** is a PHP MQTT client library that provides coroutine-based MQTT 5 functionality integrated with the Hyperf framework. Built on top of [simps/mqtt](https://github.com/simps/mqtt), this library focuses on enabling MQTT 5's shared subscription feature for load-balanced message consumption across multiple subscribers. ### Design Philosophy [](#design-philosophy) The library was specifically designed to leverage MQTT 5's **Shared Subscription** feature, which allows multiple subscribers to subscribe to the same topic while ensuring only one subscriber receives each message (load balancing). This is particularly useful for: - **Queue Topics**: `$queue/topic` - Simple load balancing - **Shared Topics**: `$share/group/topic` - Group-based load balancing with custom group names ``` [subscriber1] got msg1 msg1, msg2, msg3 / [publisher] ---------------> "$share/g/topic" -- [subscriber2] got msg2 \ [subscriber3] got msg3 ``` Architecture Overview --------------------- [](#architecture-overview) ### Core Components [](#core-components) #### Client Layer [](#client-layer) - **`Client`** (`src/Client.php`): Main facade providing proxy methods for all MQTT operations - **`ClientFactory`** (`src/ClientFactory.php`): Factory for creating client instances with proper pool management - **`ClientProxy`** (`src/ClientProxy.php`): Proxy implementation handling method delegation and connection management #### Connection Management [](#connection-management) - **`MQTTConnection`** (`src/MQTTConnection.php`): Wrapper around simps/mqtt client with Hyperf coroutine integration - **`MQTTPool`** (`src/Pool/MQTTPool.php`): Connection pool implementation for efficient resource management - **`PoolFactory`** (`src/Pool/PoolFactory.php`): Factory for creating and managing connection pools #### Configuration System [](#configuration-system) - **`ClientConfig`** (`src/Config/ClientConfig.php`): Connection configuration (broker, credentials, timeouts) - **`TopicConfig`** (`src/Config/TopicConfig.php`): Topic-specific configuration for subscriptions and publishing - **`ConfigProvider`** (`src/ConfigProvider.php`): Hyperf service provider for dependency injection and event listeners #### Event-Driven Architecture [](#event-driven-architecture) The library uses Hyperf's event system for decoupled MQTT operations: **Command Events** (trigger actions): - **`PublishEvent`**: Dispatch to publish messages - **`SubscribeEvent`**: Dispatch to subscribe to topics **Notification Events** (reactions to MQTT events): - **`OnReceiveEvent`**: Triggered when messages are received - **`OnPublishEvent`**: Triggered when messages are published - **`OnSubscribeEvent`**: Triggered when subscriptions are established - **`OnDisconnectEvent`**: Triggered on connection loss #### Listeners [](#listeners) - **`PublishListener`**: Handles PublishEvent dispatching - **`SubscribeListener`**: Handles SubscribeEvent dispatching - **`AfterWorkerStartListener`**: Handles auto-subscription on server startup - **`OnReceiveListener`**: Handles incoming message processing - **`ServerIdListener`**: Manages server identification for clustering ### Multi-Subscription Support [](#multi-subscription-support) The library supports multiple subscription patterns: 1. **Auto-subscription**: Configure topics in `mqtt.php` with `auto_subscribe: true` 2. **Multi-subscriber**: Use `enable_multisub: true` to create multiple clients for the same topic 3. **Shared subscriptions**: Configure `enable_share_topic: true` with group names 4. **Queue subscriptions**: Enable `enable_queue_topic: true` for simple load balancing Configuration ------------- [](#configuration) ### MQTT Broker Configuration [](#mqtt-broker-configuration) Key environment variables: - `MQTT_HOST`: MQTT broker host (default: localhost) - `MQTT_PORT`: MQTT broker port (default: 1883) - `MQTT_USERNAME`: MQTT username (default: admin) - `MQTT_PASSWORD`: MQTT password (default: public) - `MQTT_PROTOCOL_LEVEL`: MQTT protocol level (default: 5) ### Connection Pool Configuration [](#connection-pool-configuration) Located in `config/autoload/mqtt.php`: - `min_connections`: Minimum pool connections - `max_connections`: Maximum pool connections - `connect_timeout`: Connection timeout - `wait_timeout`: Wait timeout for pool exhaustion Usage Patterns -------------- [](#usage-patterns) ### Publishing Messages [](#publishing-messages-1) ``` // Via event dispatch $dispatcher->dispatch(new PublishEvent('topic/test', 'message', 2)); // Direct client usage $client = make(Client::class); $client->publish('topic/test', 'message', 2); ``` ### Subscribing to Topics [](#subscribing-to-topics-1) ``` // Via event dispatch $event = new SubscribeEvent(topicConfigs: [ new TopicConfig(['topic' => 'topic/test', 'qos' => 2]) ]); $dispatcher->dispatch($event); // Direct client usage $client->subscribe(['topic/test' => ['qos' => 2]]); ``` ### Auto-subscription [](#auto-subscription) Configure topics in `config/autoload/mqtt.php` with `auto_subscribe: true` to automatically subscribe when the Hyperf server starts. Dependencies ------------ [](#dependencies) - PHP >= 8.3 - Hyperf Framework ~3.1 - simps/mqtt ~2.0 - Swoole >= 5.0 or Swow >= 1.5 (extensions) Testing Requirements -------------------- [](#testing-requirements) The test suite requires: - PHPUnit with co-phpunit for coroutine testing - Hyperf testing framework - Redis for integration tests (optional) - MQTT broker running for integration tests ### Health Score 42 — FairBetter than 88% of packages Maintenance64 Regular maintenance activity Popularity21 Limited adoption so far Community8 Small or concentrated contributor base Maturity63 Established project with proven stability 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 ~66 days Recently: every ~3 days Total 22 Last Release 121d ago PHP version history (4 changes)v0.1PHP >=8.0 v0.1.1PHP >=8.1 0.1.2PHP >=8.2 v0.2.0-alphaPHP >=8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/d49d3e1396448219dc4cf8798d21bbb102e3552666baade75136a39bb72c7407?d=identicon)[nashgao](/maintainers/nashgao) --- Top Contributors [![nashgao](https://avatars.githubusercontent.com/u/9336171?v=4)](https://github.com/nashgao "nashgao (124 commits)") ### Code Quality Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/nashgao-mqtt/health.svg) ``` [![Health](https://phpackages.com/badges/nashgao-mqtt/health.svg)](https://phpackages.com/packages/nashgao-mqtt) ``` ### Alternatives [hyperf/hyperf-skeleton A coroutine framework that focuses on hyperspeed and flexible, specifically use for build microservices and middlewares. 313190.9k](/packages/hyperf-hyperf-skeleton)[hyperf/xxl-job-incubator php hyperf xxljob 4837.8k13](/packages/hyperf-xxl-job-incubator)[mineadmin/mineadmin Quickly build a background management system for web applications 1.2k2.2k](/packages/mineadmin-mineadmin)[friendsofhyperf/sentry The sentry component for Hyperf. 1974.5k](/packages/friendsofhyperf-sentry)[hyperf/odin 486.5k](/packages/hyperf-odin) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)