PHPackages                             watsonhaw/think-queue - 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. [Queues & Workers](/categories/queues)
4. /
5. watsonhaw/think-queue

ActiveLibrary[Queues & Workers](/categories/queues)

watsonhaw/think-queue
=====================

The ThinkPHP8 Queue Package

v1.3.0(1mo ago)0133↓83.3%1Apache-2.0PHPPHP >=8.0CI passing

Since Jul 2Pushed 1mo agoCompare

[ Source](https://github.com/watsonhaw5566/think-queue)[ Packagist](https://packagist.org/packages/watsonhaw/think-queue)[ RSS](/packages/watsonhaw-think-queue/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (2)Dependencies (15)Versions (6)Used By (1)

think-queue for ThinkPHP 8
==========================

[](#think-queue-for-thinkphp-8)

一个为 ThinkPHP 8 提供异步任务队列能力的组件，支持 **PHP 8.0+**。

内置驱动：

- `sync` —— 同步执行（默认，调试用）
- `database` —— 数据库驱动
- `redis` —— Redis 驱动
- `cmq` —— 腾讯云 CMQ（TDMQ-CMQ）消息队列驱动
- 自定义驱动（传入完整类名即可）

安装
--

[](#安装)

```
composer require watsonhaw/think-queue
```

安装完成后会自动在 `config/queue.php` 生成配置文件。

### 可选依赖

[](#可选依赖)

驱动依赖`redis`PHP 扩展 `redis``cmq`无依赖（原生 curl 实现）配置
--

[](#配置)

配置文件位于 `config/queue.php`，主要结构如下：

```
return [
    // 默认连接
    'default' => 'sync',

    // 各连接配置
    'connections' => [
        'sync' => [
            'type' => 'sync',
        ],
        'database' => [
            'type'       => 'database',
            'queue'      => 'default',
            'table'      => 'jobs',
            'connection' => null,
        ],
        'redis' => [
            'type'       => 'redis',
            'queue'      => 'default',
            'host'       => '127.0.0.1',
            'port'       => 6379,
            'password'   => '',
            'select'     => 0,
            'timeout'    => 0,
            'persistent' => false,
        ],
        'cmq' => [
            'type'                 => 'cmq',
            'queue'                => 'default',
            'secret_id'            => '',
            'secret_key'           => '',
            'region'               => 'ap-guangzhou',
            'endpoint'             => '',
            'polling_wait_seconds' => 0,
        ],
    ],

    // 失败任务表配置
    'failed' => [
        'type'  => 'none',
        'table' => 'failed_jobs',
    ],
];
```

### CMQ 配置项说明

[](#cmq-配置项说明)

配置项默认值说明`queue``default`默认队列名`secret_id``''`腾讯云 API 密钥 SecretId`secret_key``''`腾讯云 API 密钥 SecretKey`region``ap-guangzhou`腾讯云地域（如 `ap-guangzhou` / `ap-shanghai` / `ap-beijing` 等），用于查询队列详情（size）`endpoint``''`CMQ 原生接口入口地址，从 TDMQ CMQ 版控制台复制（如 `https://cmq-gz.publicXXX.tencenttdmq.com`），用于消息投递/消费/删除`polling_wait_seconds``0`ReceiveMessage 长轮询等待时长（0 表示短轮询，最大 30 秒）创建任务类
-----

[](#创建任务类)

推荐使用 `app\job` 作为任务类的命名空间，也可放在任意可自动加载的目录。

任务类无需继承任何类，只需约定：

方法说明`fire(Job $job, mixed $data)` / 任意自定义方法名任务执行入口，接受当前任务对象和自定义数据`failed(mixed $data)`（可选）任务达到最大重试次数后调用### 单任务类示例

[](#单任务类示例)

```
namespace app\job;

use think\queue\Job;

class SendEmail
{
    public function fire(Job $job, mixed $data): void
    {
        // 执行具体任务，例如发送邮件
        // ...

        // 检查当前重试次数
        if ($job->attempts() > 3) {
            // 已重试 3 次仍未成功
            $job->delete();
            return;
        }

        // 执行成功后手动删除任务（否则会重复执行）
        $job->delete();

        // 或重新发布（延迟执行）
        // $job->release(60);
    }

    public function failed(mixed $data): void
    {
        // 任务达到最大重试次数后的逻辑
    }
}
```

### 多任务类示例（一个类多个任务入口）

[](#多任务类示例一个类多个任务入口)

```
namespace app\job;

use think\queue\Job;

class Notification
{
    public function sendEmail(Job $job, mixed $data): void
    {
        // ...
    }

    public function sendSms(Job $job, mixed $data): void
    {
        // ...
    }

    public function failed(mixed $data): void
    {
        // ...
    }
}
```

使用 `Queueable` 链式调用
-------------------

[](#使用-queueable-链式调用)

任务类可以使用 `think\queue\Queueable` trait，在发布任务时进行链式配置：

```
use think\queue\ShouldQueue;
use think\queue\Queueable;

class SendEmail implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        // 任务逻辑
    }
}
```

发布时：

```
use think\facade\Queue;

(new SendEmail())
    ->onConnection('redis')   // 指定连接
    ->onQueue('high')         // 指定队列
    ->delay(30)               // 延迟 30 秒
    ->dispatch();             // 发布到队列

// 或直接使用门面：
Queue::push(SendEmail::class);
Queue::later(60, SendEmail::class, ['key' => 'value']);
```

发布任务
----

[](#发布任务)

通过门面类 `\think\facade\Queue` 发布任务：

```
use think\facade\Queue;

// 立即发布（使用默认连接与队列）
Queue::push('app\job\SendEmail', ['to' => 'user@example.com');

// 指定队列
Queue::push('app\job\SendEmail', ['to' => 'user@example.com'], 'high');

// 延迟发布（$delay 秒后执行）
Queue::later(300, 'app\job\SendEmail', ['to' => 'user@example.com']);

// 多任务类时，使用 @method 语法
Queue::push('app\job\Notification@sendSms', ['to' => '13800138000']);
```

`push` 与 `later` 的返回值：

- `sync` 驱动：`null`（同步执行完成）
- `database` 驱动：任务 ID（`int`）
- `redis` 驱动：`true`（成功时）
- `cmq` 驱动：消息 `MsgId` 字符串

监听任务并执行
-------

[](#监听任务并执行)

### `queue:work` —— 单进程消费（推荐常驻）

[](#queuework--单进程消费推荐常驻)

```
# 使用默认连接
php think queue:work

# 指定连接和队列
php think queue:work redis --queue=high

# 使用 CMQ 驱动
php think queue:work cmq --queue=high

# 仅执行一次后退出
php think queue:work --once

# 配置参数
php think queue:work redis --queue=default --delay=0 --memory=128 --sleep=3 --tries=0
```

参数说明：

参数默认值说明`connection``config('queue.default')`使用的队列连接名称`--queue``default`监听的队列名，多个用逗号分隔`--once`—仅处理一个任务后退出`--delay``0`任务失败后重新入队的延迟秒数`--memory``128`内存限制（MB），超出后进程终止`--sleep``3`队列空时的休眠秒数`--tries``0`任务最大重试次数，`0` 表示无限重试### `queue:listen` —— 守护进程监听（会反复 fork worker）

[](#queuelisten--守护进程监听会反复-fork-worker)

```
php think queue:listen
php think queue:listen redis --queue=high --delay=0 --memory=128 --sleep=3 --tries=0
```

> 生产环境推荐配合 **supervisor** 或 systemd 保证进程常驻。

数据库驱动表迁移
--------

[](#数据库驱动表迁移)

使用 `database` 驱动前需要创建 `jobs` 数据表：

```
php think queue:table
php think migrate:run
```

如果需要记录失败任务：

```
php think queue:failed-table
php think migrate:run
```

CMQ 驱动说明
--------

[](#cmq-驱动说明)

CMQ 驱动基于腾讯云 CMQ（TDMQ-CMQ），使用原生 `SendMessage` / `ReceiveMessage` / `DeleteMessage` 等 JSON API，无需自建消息中间件。

### 关键特点

[](#关键特点)

- **延迟投递**：`later()` 使用 CMQ 原生 `DelaySeconds` 参数，无需应用层维护 delayed/reserved 队列
- **长轮询**：支持 `PollingWaitSeconds`（0-30 秒），减少空轮询开销
- **消费确认**：任务执行成功后调用 `$job->delete()`，对应 CMQ `DeleteMessage`
- **发布与重新入队**：`$job->release(int $delay)` 先删除原消息，再投递一条含最新 `attempts` 的新消息（可带 `DelaySeconds`），使 `maxTries` 与 failed 机制正常工作

### 延迟控制消息

[](#延迟控制消息)

```
use think\facade\Queue;

// 立即投递到默认队列（CMQ 队列名：`default`）
Queue::connection('cmq')->push('app\job\SendEmail', ['to' => 'user@example.com']);

// 延迟 5 分钟投递（CMQ 原生支持）
Queue::connection('cmq')->later(300, 'app\job\SendEmail', ['to' => 'user@example.com']);

// 推送到指定队列
Queue::connection('cmq')->push('app\job\SendEmail', [], 'high');
```

失败任务管理
------

[](#失败任务管理)

命令作用`php think queue:failed`列出所有失败的任务`php think queue:retry `重新发布指定 ID 的失败任务`php think queue:retry all`重新发布所有失败任务`php think queue:forget `删除指定 ID 的失败任务`php think queue:flush`清空所有失败任务任务事件
----

[](#任务事件)

组件在任务生命周期会触发以下事件，可在事件订阅者中监听：

事件类触发时机公开属性（均为 `readonly`）`think\queue\event\JobProcessing`任务开始执行前`$connection`, `$job``think\queue\event\JobProcessed`任务执行完成后`$connection`, `$job``think\queue\event\JobExceptionOccurred`任务执行过程中出现异常`$connection`, `$job`, `$exception``think\queue\event\JobFailed`任务失败（超过最大重试次数）`$connection`, `$job`, `$exception``think\queue\event\WorkerStopping`Worker 进程停止前`$status`示例：

```
use think\queue\event\JobFailed;

$this->app->event->listen(JobFailed::class, function (JobFailed $event): void {
    // 通过 public readonly 属性直接访问
    $connection = $event->connection;
    $exception  = $event->exception;
    $payload    = $event->job->payload();

    // 日志、告警等
});
```

版本与要求
-----

[](#版本与要求)

项版本ThinkPHP`^8.0`PHP`>= 8.0`可选扩展`redis`（使用 redis 驱动时）、`pcntl`（信号处理，可选）

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance91

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 69.5% 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 ~4 days

Total

4

Last Release

35d ago

### Community

Maintainers

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

---

Top Contributors

[![yunwuxin](https://avatars.githubusercontent.com/u/2168125?v=4)](https://github.com/yunwuxin "yunwuxin (73 commits)")[![liu21st](https://avatars.githubusercontent.com/u/1111670?v=4)](https://github.com/liu21st "liu21st (15 commits)")[![watsonhaw5566](https://avatars.githubusercontent.com/u/4210367?v=4)](https://github.com/watsonhaw5566 "watsonhaw5566 (9 commits)")[![coolseven](https://avatars.githubusercontent.com/u/9546869?v=4)](https://github.com/coolseven "coolseven (3 commits)")[![yangweijie](https://avatars.githubusercontent.com/u/1614114?v=4)](https://github.com/yangweijie "yangweijie (1 commits)")[![lilwil](https://avatars.githubusercontent.com/u/11472237?v=4)](https://github.com/lilwil "lilwil (1 commits)")[![cexll](https://avatars.githubusercontent.com/u/26520956?v=4)](https://github.com/cexll "cexll (1 commits)")[![jasonencode](https://avatars.githubusercontent.com/u/2210843?v=4)](https://github.com/jasonencode "jasonencode (1 commits)")[![baiy](https://avatars.githubusercontent.com/u/2341581?v=4)](https://github.com/baiy "baiy (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/watsonhaw-think-queue/health.svg)

```
[![Health](https://phpackages.com/badges/watsonhaw-think-queue/health.svg)](https://phpackages.com/packages/watsonhaw-think-queue)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.9k556.2M21.5k](/packages/laravel-framework)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k99.8M355](/packages/laravel-horizon)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.9M535](/packages/pimcore-pimcore)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k39.6k](/packages/matomo-matomo)[illuminate/queue

The Illuminate Queue package.

20433.0M1.8k](/packages/illuminate-queue)[lion/bundle

Lion-framework configuration and initialization package

132.4k5](/packages/lion-bundle)

PHPackages © 2026

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