PHPackages                             workbunny/webman-rqueue - 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. [Caching](/categories/caching)
4. /
5. workbunny/webman-rqueue

ActiveLibrary[Caching](/categories/caching)

workbunny/webman-rqueue
=======================

Webman plugin workbunny/webman-rqueue

2.2.8(5mo ago)236934MITPHPPHP ^8.0CI passing

Since Jul 1Pushed 5mo agoCompare

[ Source](https://github.com/workbunny/webman-rqueue)[ Packagist](https://packagist.org/packages/workbunny/webman-rqueue)[ RSS](/packages/workbunny-webman-rqueue/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (49)Used By (0)

[![workbunny](https://camo.githubusercontent.com/e2b1164338390ab45783434659e3e419e0c3b50fbe140c697ba1f82f59015ad6/68747470733a2f2f6368617a366368657a2e636e2f696d616765732f776f726b62756e6e792d6c6f676f2e706e67)](https://camo.githubusercontent.com/e2b1164338390ab45783434659e3e419e0c3b50fbe140c697ba1f82f59015ad6/68747470733a2f2f6368617a366368657a2e636e2f696d616765732f776f726b62756e6e792d6c6f676f2e706e67)

**workbunny/webman-rqueue**

**🐇 A lightweight queue based on Redis Stream for webman plugin. 🐇**

A lightweight queue based on Redis Stream for webman plugin
===========================================================

[](#a-lightweight-queue-based-on-redis-stream-for-webman-plugin)

 [ ![Build Status](https://github.com/workbunny/webman-rqueue/actions/workflows/CI.yml/badge.svg) ](https://github.com/workbunny/webman-rqueue/actions) [ ![PHP Version Require](https://camo.githubusercontent.com/cced531386c356c553c02b17d64ca610eb1eb59b913c307225797ee638583389/68747470733a2f2f62616467656e2e6e65742f7061636b61676973742f7068702f776f726b62756e6e792f7765626d616e2d727175657565) ](https://github.com/workbunny/webman-rqueue/blob/master/composer.json) [ ![GitHub license](https://camo.githubusercontent.com/2ace32ec84cbaff571aaaa0260a1c75fc87f226d35a2e33d7810ad973709f718/68747470733a2f2f62616467656e2e6e65742f7061636b61676973742f6c6963656e73652f776f726b62756e6e792f7765626d616e2d727175657565) ](https://github.com/workbunny/webman-rqueue/blob/master/LICENSE)

常见问题
----

[](#常见问题)

1. 什么时候使用消息队列？

    **当你需要对系统进行解耦、削峰、异步的时候；如发送短信验证码、秒杀活动、资产的异步分账清算等。**
2. RabbitMQ和Redis的区别？

    **Redis中的Stream的特性同样适用于消息队列，并且也包含了比较完善的ACK机制，但在一些点上与RabbitMQ存在不同：**

    - **Redis Stream没有完善的后台管理；RabbitMQ拥有较为完善的后台管理及Api；**
    - **Redis的持久化策略取舍：默认的RDB策略极端情况下存在丢失数据，AOF策略则需要牺牲一些性能；RabbitMQ持久化方案更多，可对消息持久化也可对队列持久化；**
    - **RabbitMQ拥有更多的插件可以提供更完善的协议支持及功能支持；**
3. 什么时候使用Redis？什么时候使用RabbitMQ？

    **当你的队列使用比较单一或者比较轻量的时候，请选用 Redis Stream；当你需要一个比较完整的消息队列体系，包括需要利用交换机来绑定不同队列做一些比较复杂的消息任务的时候，请选择RabbitMQ；**

    **当然，如果你的队列使用也比较单一，但你需要用到一些管理后台相关系统化的功能的时候，又不想花费太多时间去开发的时候，也可以使用RabbitMQ；因为RabbitMQ提供了一整套后台管理的体系及 HTTP API 供开发者兼容到自己的管理后台中，不需要再消耗多余的时间去开发功能；**

    注：这里的 **轻量** 指的是 **无须将应用中的队列服务独立化，该队列服务是该应用独享的**

简介
--

[](#简介)

- 基于Redis Stream的轻量级队列；
- [Queue 模式：多个消费者竞争消费](#queue)
    - 支持普通消费
    - 支持延迟消费
- [Group 模式：多个消费组订阅消费](#group)
    - 支持普通消费
    - 支持延迟消费
- [Adaptive 模式：Queue的自适应版消费者](#adaptive)
    - 支持普通消费
    - 支持延迟消费
- [可靠的重载机制，防止消息意外丢失/重复消费](#temp)
    - 使用本地sqlite库储存因意外中断的消息
    - 自动加载本地消息至队列
- 简单易用容易理解的使用方式
    - 丰富的命令行助手，助手函数
    - BuilderClass继承模式（类似ORM的ModelClass）
    - [支持自定义BuilderClass，实现自定义的消费逻辑](#custom)

安装
--

[](#安装)

### 环境依赖

[](#环境依赖)

- **php >=8.0**
- **webman >= 1.0**
- **redis >= 6.2**

```
composer require workbunny/webman-rqueue

```

使用
--

[](#使用)

### QueueBuilder

[](#queuebuilder)

- 一个QueueBuilder类对应一个消费Group和一个消费逻辑 `QueueBuilder::handler()`
- 一个QueueBuilder可对应一个/多个Redis-Stream-Key，通过配置 `QueueBuilder::$config['queues']`
- QueueBuilder类使用定时器进行消费，每一次消费之后会根据消息的属性 `_header['_delete']` 来进行消息释放

#### 命令行

[](#命令行)

**--mode默认为queue**

- 创建

```
# 创建一个拥有单进程消费者的QueueBuilder
./webman workbunny:rqueue-builder testQueue --mode=queue
./webman workbunny:rqueue-builder testQueue -m queue
# 创建一个拥有4进程消费者的QueueBuilder
./webman workbunny:rqueue-builder testQueue 4 --mode=queue
./webman workbunny:rqueue-builder testQueue 4 -m queue
# 创建一个拥有单进程消费者的延迟QueueBuilder
./webman workbunny:rqueue-builder testQueue --delayed --mode=queue
./webman workbunny:rqueue-builder testQueue -dm queue
# 创建一个拥有4进程消费者的延迟QueueBuilder
./webman workbunny:rqueue-builder testQueue 4 --delayed --mode=queue
./webman workbunny:rqueue-builder testQueue 4 -dm queue

# 在 process/workbunny/rqueue 目录下创建 TestQueueBuilder.php
./webman workbunny:rqueue-builder testQueue
# 在 process/workbunny/rqueue/project 目录下创建 TestQueueBuilder.php
./webman workbunny:rqueue-builder project/testQueue
# 在 process/workbunny/rqueue/project 目录下创建 TestAllQueueBuilder.php
./webman workbunny:rqueue-builder project/testAllQueue
# 延迟同理
```

- 移除

移除包含了类文件的移除和配置的移除

```
# 移除Builder
./webman workbunny:rqueue-remove testQueue
# 移除延迟Builder
./webman workbunny:rqueue-remove testQueue --delayed
./webman workbunny:rqueue-remove testQueue -d
# 二级菜单同理
```

- 开启

开启仅对配置进行移除

```
# 开启Builder
./webman workbunny:rqueue-builder test --open --mode=queue
./webman workbunny:rqueue-builder test -om queue
# 开启延迟Builder
./webman workbunny:rqueue-builder test --open --delayed --mode=queue
./webman workbunny:rqueue-builder test -odm queue

# 二级菜单同理
```

- 关闭

关闭仅对配置进行移除

```
# 关闭Builder
./webman workbunny:rqueue-remove test --close --mode=queue
./webman workbunny:rqueue-remove test -cm queue
# 关闭延迟Builder
./webman workbunny:rqueue-remove test --close --delayed --mode=queue
./webman workbunny:rqueue-remove test -cdm queue

# 二级菜单同理
```

### GroupBuilder

[](#groupbuilder)

- 一个GroupBuilder类对应一个消费Group和一个消费逻辑 `QueueBuilder::handler()`
- 一个GroupBuilder可对应一个/多个Redis-Stream-Key，通过配置 `QueueBuilder::$config['queues']`
- GroupBuilder类使用定时器进行消费，使用定时器释放当前 Stream-Key 上**所有Group收取过的闲置消息**
- 可以使用多个GroupBuilder类配置相同的 `QueueBuilder::$config['queues']`，从而达到一条/多条队列由不同的消费逻辑进行处理；
    - 基于此特性，可以实现消息持久化的发布订阅
    - 基于此特性，可以实现RabbitMQ的exchange模式

#### 命令行

[](#命令行-1)

- 创建

```
# 创建一个拥有单进程消费者的GroupBuilder
./webman workbunny:rqueue-builder testGroup --mode=group
./webman workbunny:rqueue-builder testGroup -m group
# 创建一个拥有4进程消费者的GroupBuilder
./webman workbunny:rqueue-builder testGroup 4 --mode=group
./webman workbunny:rqueue-builder testGroup 4 -m group
# 创建一个拥有单进程消费者的延迟GroupBuilder
./webman workbunny:rqueue-builder testGroup --delayed--mode=group
./webman workbunny:rqueue-builder testGroup -dm group
# 创建一个拥有4进程消费者的延迟GroupBuilder
./webman workbunny:rqueue-builder testGroup 4 --delayed--mode=group
./webman workbunny:rqueue-builder testGroup 4 -dm group

# 二级菜单

# 在 process/workbunny/rqueue 目录下创建 TestGroupBuilder.php
./webman workbunny:rqueue-builder testGroup --mode=group
./webman workbunny:rqueue-builder testGroup -m group
# 在 process/workbunny/rqueue/project 目录下创建 TestGroupBuilder.php
./webman workbunny:rqueue-builder project/testGroup --mode=group
./webman workbunny:rqueue-builder project/testGroup -m group
# 在 process/workbunny/rqueue/project 目录下创建 TestAllGroupBuilder.php
./webman workbunny:rqueue-builder project/testAllGroup --mode=group
./webman workbunny:rqueue-builder project/testAllGroup -m group
```

- 移除

移除包含了类文件的移除和配置的移除

```
# 移除Builder
./webman workbunny:rqueue-remove testGroup --mode=group
./webman workbunny:rqueue-remove testGroup -m group
# 移除延迟Builder
./webman workbunny:rqueue-remove testGroup --delayed --mode=group
./webman workbunny:rqueue-remove testGroup -dm group
# 二级菜单同理
```

- 开启

开启仅对配置进行移除

```
# 开启Builder
./webman workbunny:rqueue-builder testGroup --open --mode=group
./webman workbunny:rqueue-builder testGroup -om group
# 开启延迟Builder
./webman workbunny:rqueue-builder testGroup --open --delayed --mode=group
./webman workbunny:rqueue-builder testGroup -odm group
# 二级菜单同理
```

- 关闭

关闭仅对配置进行移除

```
# 关闭Builder
./webman workbunny:rqueue-remove testGroup --close --mode=group
./webman workbunny:rqueue-remove testGroup -cm group
# 关闭延迟Builder
./webman workbunny:rqueue-remove testGroup --close --delayed --mode=group
./webman workbunny:rqueue-remove testGroup -cdm group
# 二级菜单同理
```

### AdaptiveBuilder

[](#adaptivebuilder)

#### 说明

[](#说明)

- AdaptiveBuilder与QueueBuilder的消费方式一致
- AdaptiveBuilder底层定时器会根据*闲置阈值*进行判断，消费定时器根据*退避指数* x *当前消费间隔*进行重置消费间隔

#### 相较于其他Builder的优势

[](#相较于其他builder的优势)

- 在消息负载较高的情况下，AdaptiveBuilder是普通的QueueBuilder
- 在消息负载较低的情况下，AdaptiveBuilder根据闲置阈值对消费者的消费查询速率进行自适应退避调整，有效减少redis的查询压力
- 在延时消费场景下，AdaptiveBuilder能有效减少因频繁查询redis而造成的redis-server CPU占用率较高的问题
- 在普通消费模式下，AdaptiveBuilder相比于其他Builder能更快启动下一个消费周期，无需等待Timer的下一个loop，消费更及时

#### 命令行

[](#命令行-2)

- 创建

```
# 创建一个拥有单进程消费者的AdaptiveBuilder
./webman workbunny:rqueue-builder testAdaptive --mode=adaptive
./webman workbunny:rqueue-builder testAdaptive -m adaptive
# 创建一个拥有4进程消费者的AdaptiveBuilder
./webman workbunny:rqueue-builder testAdaptive 4 --mode=adaptive
./webman workbunny:rqueue-builder testAdaptive 4 -m adaptive
# 创建一个拥有单进程消费者的延迟AdaptiveBuilder
./webman workbunny:rqueue-builder testAdaptive --delayed--mode=adaptive
./webman workbunny:rqueue-builder testAdaptive -dm adaptive
# 创建一个拥有4进程消费者的延迟AdaptiveBuilder
./webman workbunny:rqueue-builder testAdaptive 4 --delayed--mode=adaptive
./webman workbunny:rqueue-builder testAdaptive 4 -dm adaptive

# 二级菜单

# 在 process/workbunny/rqueue 目录下创建
./webman workbunny:rqueue-builder testAdaptive --mode=adaptive
./webman workbunny:rqueue-builder testAdaptive -m adaptive
# 在 process/workbunny/rqueue/project 目录下创建
./webman workbunny:rqueue-builder project/testAdaptive --mode=adaptive
./webman workbunny:rqueue-builder project/testAdaptive -m adaptive
# 在 process/workbunny/rqueue/project 目录下创建
./webman workbunny:rqueue-builder project/testAllAdaptive --mode=adaptive
./webman workbunny:rqueue-builder project/testAllAdaptive -m adaptive
```

- 移除

移除包含了类文件的移除和配置的移除

```
# 移除Builder
./webman workbunny:rqueue-remove testAdaptive --mode=adaptive
./webman workbunny:rqueue-remove testAdaptive -m adaptive
# 移除延迟Builder
./webman workbunny:rqueue-remove testAdaptive --delayed --mode=adaptive
./webman workbunny:rqueue-remove testAdaptive -dm adaptive
# 二级菜单同理
```

- 开启

开启仅对配置进行移除

```
# 开启Builder
./webman workbunny:rqueue-builder testAdaptive --open --mode=adaptive
./webman workbunny:rqueue-builder testAdaptive -om adaptive
# 开启延迟Builder
./webman workbunny:rqueue-builder testAdaptive --open --delayed --mode=adaptive
./webman workbunny:rqueue-builder testAdaptive -odm adaptive
# 二级菜单同理
```

- 关闭

关闭仅对配置进行移除

```
# 关闭Builder
./webman workbunny:rqueue-remove testAdaptive --close --mode=adaptive
./webman workbunny:rqueue-remove testAdaptive -cm adaptive
# 关闭延迟Builder
./webman workbunny:rqueue-remove testAdaptive --close --delayed --mode=adaptive
./webman workbunny:rqueue-remove testAdaptive -cdm adaptive
# 二级菜单同理
```

### 自定义Builder

[](#自定义builder)

如queue/group Builder都不满足需求，您可继承 AbstractBuilder 自行实现您所需要的Builder

- 您的Builder基类需要继承AbstractBuilder实现，可参考QueueBuilder/GroupBuilder
    - onWorkerStart 用于进程启动时的触发逻辑， 这里一般使用Timer结合读取队列触发callback来实现消费队列
    - onWorkerStop 用于进程停止时的回收动作
    - onWorkerReload 用于进程重载时的触发动作，除非有特殊处理，通常置空

```
    /*
     * Builder 启动时
     *
     * @param Worker $worker
     * @return void
     */
    abstract public function onWorkerStart(Worker $worker): void;

    /**
     * Builder 停止时
     *
     * @param Worker $worker
     * @return void
     */
    abstract public function onWorkerStop(Worker $worker): void;

    /**
     * Builder 重加载时
     *
     * @param Worker $worker
     * @return void
     */
    abstract public function onWorkerReload(Worker $worker): void;
```

- classContent方法是配合命令行，用于自动生成队列文件，如不使用，可置空

```
    /**
     * Command 获取需要创建的类文件内容
     *
     * @param string $namespace
     * @param string $className
     * @param bool $isDelay
     * @return string
     */
    abstract public static function classContent(string $namespace, string $className, bool $isDelay): string;
```

- Traits类提供所需的基础方法，按需在您的Builder基类中引用
    - MessageQueueMethod 提供针对redis-stream队列的基础操作，如ack、publish、consume等、
    - MessageTempMethod 提供本地数据缓存，用于对异常数据的收集和requeue
    - 如上述traits无法满足需求，可自定义Traits

### 注意

[](#注意)

- **QueueBuilder与GroupBuilder在命令行自动生成时没有做类似Delayed的区分，用户可自行进行命名区分，如：**

```
# 创建一个GroupBuilder
./webman workbunny:rqueue-builder testGroup --mode=group
# 创建一个QueueBuilder
./webman workbunny:rqueue-builder testQueue --mode=queue
```

- **创建的Builder类可以手动修改调整**
- **为Builder添加进process.php的配置可以手动修改**

### 查看Builder

[](#查看builder)

```
./webman workbunny:rqueue-list
```

**注：当 Builder 未启动时，handler 与 count 显示为 --**

```
+----------+-----------------------------------------------------------------------+-------------------------------------------------+-------+-------+
| name     | file                                                                  | handler                                         | count | mode  |
+----------+-----------------------------------------------------------------------+-------------------------------------------------+-------+-------+
| test     | /var/www/your-project/process/workbunny/rqueue/TestBuilder.php        | process\workbunny\rqueue\TestBuilder            | 1     | queue |
| test -d  | /var/www/your-project/process/workbunny/rqueue/TestBuilderDelayed.php | process\workbunny\rqueue\TestBuilderDelayed     | 1     | group |
+----------+-----------------------------------------------------------------------+-------------------------------------------------+-------+-------+
```

### 生产

[](#生产)

#### 发布普通消息

[](#发布普通消息)

**注：向普通队列发布延迟消息会抛出一个 WebmanRqueueException 异常**

```
use function Workbunny\WebmanRqueue\sync_publish;
use function Workbunny\WebmanRqueue\sync_publish_get_ids;
use process\workbunny\rqueue\TestBuilder;

# 使用函数发布，返回受影响条数，多队列不具备事务一致
/** headers参数详见 @link Header */
sync_publish(TestBuilder::instance(), 'abc', [
	'_delete' => false
]);

# 使用对象发布，返回受影响条数，多队列不具备事务一致
/** headers参数详见 @link Header */
TestBuilder::instance()->publish('abc', [
	'_delete' => false
]);

# 返回消息ID组(数组)，多队列不具备事务一致
sync_publish_get_ids(TestBuilder::instance(), 'abc', [
	'_delete' => false
]);

# 返回消息ID组(数组)，多队列不具备事务一致
TestBuilder::instance()->publishGetIds('abc', [
	'_delete' => false
]);
```

#### 发布延迟消息

[](#发布延迟消息)

**注：向延迟队列发布普通消息会抛出一个 WebmanRqueueException 异常****注：延迟队列发布消息不支持指定消息id**

```
use function Workbunny\WebmanRqueue\sync_publish;
use function Workbunny\WebmanRqueue\sync_publish_get_ids;
use process\workbunny\rqueue\TestBuilder;

# 延迟10ms，返回受影响条数，多队列不具备事务一致
sync_publish(TestBuilder::instance(), 'abc', [
	'_delay' => 10
]);

# 延迟10ms，返回受影响条数，多队列不具备事务一致
TestBuilder::instance()->publish('abc', [
	'_delay' => 10
]);

# 延迟10ms，返回消息ID组(数组)，多队列不具备事务一致
sync_publish_get_ids(TestBuilder::instance(), 'abc', [
	'_delay' => 10
]);

# 延迟10ms，返回消息ID组(数组)，多队列不具备事务一致
TestBuilder::instance()->publishGetIds('abc', [
	'_delay' => 10
]);
```

说明
--

[](#说明-1)

- **生产可用，欢迎 [issue](https://github.com/workbunny/webman-rqueue/issues) 和 PR**；
- **Redis Stream** 本身没有 **delayed** 或 **non-delayed** 之分，组件代码将它们区分的原因是不希望 **delayed** 被滥用；开发者应该明确哪些消息是延迟的、哪些是立即的，并且明确体现，也方便维护，因为延迟消息过多会导致消息堆积，从而占用Redis过多的资源；
- 延迟队列是通过对消息的不断读取放回并且加以判断是否达到延迟触发时间来进行模拟延迟触发的效果，消息不支持指定id，请在逻辑内自行实现；
- **Redis Stream** 的持久化依赖 **Redis** 本身的持久化策略，在一定情况下 **Redis Stream** 也并非是可靠型的消息队列;关于持久化相关内容，请仔细阅读 **[Redis中文文档](http://www.redis.cn/topics/persistence.html)**；
- 本地重载机制使用了SQLite3，详见 **src/Builders/Traits/MessageTempMethod**

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance70

Regular maintenance activity

Popularity27

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 97.1% 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 ~26 days

Recently: every ~75 days

Total

48

Last Release

176d ago

Major Versions

0.0.2 → 1.0.02022-07-04

1.x-dev → 2.0.02023-04-24

PHP version history (3 changes)0.0.1PHP >=7.4

2.0.0PHP ^8.1

2.1.1PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/d1b317277226c93c11984f73dfad75533893466b02d06611126aa1687209c6ab?d=identicon)[Chaz6Chez](/maintainers/Chaz6Chez)

---

Top Contributors

[![chaz6chez](https://avatars.githubusercontent.com/u/22535862?v=4)](https://github.com/chaz6chez "chaz6chez (132 commits)")[![fuzqing](https://avatars.githubusercontent.com/u/15156836?v=4)](https://github.com/fuzqing "fuzqing (4 commits)")

---

Tags

queuerediswebmanwebman-pluginworkbunny

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/workbunny-webman-rqueue/health.svg)

```
[![Health](https://phpackages.com/badges/workbunny-webman-rqueue/health.svg)](https://phpackages.com/packages/workbunny-webman-rqueue)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.7k509.9M17.0k](/packages/laravel-framework)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

44643.1k1](/packages/pressbooks-pressbooks)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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