# yii2-queue: one job API across seven queue brokers

> yii2-queue is the Yii2 extension for running tasks asynchronously, and its selling point is the breadth of the backends it hides behind one API: database, Redis, RabbitMQ, AMQP, Beanstalk, ActiveMQ and Gearman. Jobs are ordinary classes, workers are console commands, and job status can be polled by message id.

**yiisoft/yii2-queue** — Yii2 Queue Extension. Supports DB, Redis, RabbitMQ, Beanstalk and Gearman

- Repository: https://github.com/yiisoft/yii2-queue
- Website: http://www.yiiframework.com
- Stars: 1,062 · Forks: 286
- Language: PHP
- License: BSD-3-Clause
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/yiisoft-yii2-queue

## The broker is a configuration detail, not an architectural one

The extension does one thing: run tasks asynchronously through a queue. The interesting decision is how many brokers it hides. The README lists support for queues based on DB, Redis, RabbitMQ, AMQP, Beanstalk, ActiveMQ and Gearman, and the repository description adds DB, Redis, RabbitMQ, Beanstalk and Gearman to the same set.

That breadth is the reason to look at this extension if you already run Yii2. A team that has a database and nothing else can start with the database driver, and a team that later provisions Redis or RabbitMQ can switch without rewriting the jobs, because a job is a class rather than a message format. The risk of that flexibility is that it defers the real question. Which broker you pick determines your delivery semantics, and the extension does not paper over that, it just lets you postpone the decision.

The development environment reflects the same breadth. The compose file brings up MySQL, Postgres, Redis, RabbitMQ, Beanstalk, Gearman, ActiveMQ and a LocalStack instance for SQS, and every one of them is a dependency of the PHP container, so the test suite exercises the drivers against real services rather than against mocks.

## A job is a class with an execute method

Each task sent to the queue is defined as a separate class, and the example in the README is a download job. It extends BaseObject and implements the queue's JobInterface, with the work in an execute method that receives the queue:

```php
Yii::$app->queue->push(new DownloadJob([
    'url' => 'http://example.com/image.jpg',
    'file' => '/tmp/image.jpg',
]));
```

The shape matters more than the example. A job carries its parameters as public properties, so the same class describes both the unit of work and the data it needs, and the driver decides how that object is serialised onto the queue. That is the mechanism behind the driver independence: the job is never written as a bespoke payload format for one broker.

Delaying a job is the same call with a delay in front of it, so a task that should run in five minutes is pushed with a delay of 5 * 60 seconds rather than being scheduled by an external scheduler.

## run drains the queue, listen stays on it

How a task is executed depends on the driver, but most drivers can be run through console commands that the component registers in your application automatically. Two of those commands matter.

The first obtains and executes tasks in a loop until the queue is empty:

```sh
yii queue/run
```

The second launches a daemon which infinitely queries the queue:

```sh
yii queue/listen
```

The difference is the shape of the deployment. The run command is a batch worker: it picks up whatever is there, finishes it, and exits, which fits a cron driven setup or a container that should exit when idle. The listen command is the long running one, and it is the shape most people picture when they say queue worker.

The documentation also points out that drivers have their own console commands and options, so the two commands above are the common path rather than the full story. A team that needs per-driver tuning, specific timeouts or a different reservation strategy ends up reading the driver documentation, and that is where the abstraction starts to leak.

## Polling a job by message id

The component can also track the status of a job that was pushed, and the API is a small set of predicates on a message id. Pushing returns that id:

```php
// Push a job into the queue and get a message ID.
$id = Yii::$app->queue->push(new SomeJob());

// Check whether the job is waiting for execution.
Yii::$app->queue->isWaiting($id);

// Check whether a worker got the job from the queue and executes it.
Yii::$app->queue->isReserved($id);

// Check whether a worker has executed the job.
Yii::$app->queue->isDone($id);
```

The three states are the useful part. Waiting means the job is queued and nobody has taken it. Reserved means a worker has it and is running it, which is the state that tells you a job is stuck rather than slow. Done means it finished. Note what is not here: there is no failed state, and no return value from the job. The mechanism answers whether the queue system has processed your task, not whether the task succeeded, so the status check is an aid for the user interface and not a substitute for recording the outcome in your own tables.

That limitation is worth designing around. A job that fails halfway leaves the same trace as a job that never started, and a system that reports progress to users usually needs the second kind of information too.

## Composer install, and a PHP 8.3 floor

Installation is a composer command, and the README marks the PHP requirement as important rather than incidental. The minimum required PHP version is 8.3:

```bash
php composer.phar require --prefer-dist yiisoft/yii2-queue
```

A PHP floor of 8.3 is a real constraint for a library of this age. The extension has been around long enough to have a 1.0.0, a 1.1.0 and a 2.0.2 release, and the versions in the repository are from 2017, but the current branch expects a recent runtime. If your platform is still on PHP 8.0 or 8.1, this is the point where the plan changes, and the UPGRADE.md file at the root is the place to look for what the newer requirements are.

The distribution is a standard Composer package with a single package name, and the project is published on Packagist with the usual stable version and download badges. For a Yii2 application, adding the dependency and configuring the queue component is the whole installation story.

## The test environment is eight brokers and a Makefile

The development setup is unusually thorough, and the Makefile is the entry point. The build target starts the compose stack and creates the SQS queues, the test target runs PHPUnit inside the container with coverage, and there are separate targets for static analysis with PHPStan, a benchmark run and a shell into the container. Each accepts a PHP version parameter that defaults to 8.3.

The Dockerfile for that stack is a development image, and the comment at the top says it plainly: it is not to be used in production. It builds on the PHP CLI Alpine image with the Alpine edge repositories added, installs the native libraries the drivers need including libpq, gearman and rabbitmq-c, and compiles the PHP extensions pcntl, bcmath, pdo_mysql, intl, pdo_pgsql and sockets, plus igbinary, pcov, amqp and xdebug through PECL. The Gearman extension is compiled from a git clone of the PECL source because, as the comment says, the official Gearman package does not support PHP 8.5.

That is a lot of machinery, and it is the price of testing eight brokers rather than one. For a user of the extension it means the test suite is honest about the drivers, and for a contributor it means a local run needs Docker and network access to the package mirrors.

## Maintenance, versioning and what to check first

The branch moves. The last push was on 2026-10-14, and the repository carries a GitHub Actions build badge, a codecov badge, a static analysis badge and a phpstan baseline, so the code is checked continuously even though the release tags are old, with 2.0.2 from 2017 being the newest listed version.

That gap between an active branch and a stale tag list is the practical warning for anyone pinning a version. The Composer package resolves to whatever the branch or tag says, and the documentation on the branch expects PHP 8.3, so a project that installed the package years ago and upgrades now is crossing a major version gap, and UPGRADE.md plus CHANGELOG.md are the documents to read before doing it.

The licence is BSD-3-Clause, which is permissive and requires that the notice travels with redistribution, and the project accepts sponsorship through Open Collective.

So the adoption picture is: good for a Yii2 team that wants background jobs and values the ability to change brokers, needing an active branch rather than an old tag, comfortable with PHP 8.3, and willing to own the parts the extension leaves open, namely failure reporting, retries and the job's own result, since the status API only tells you whether the queue processed the task and not whether it succeeded.

## Conclusion

yii2-queue fits a Yii2 application that needs background work and does not want to commit to one broker, or that already has one of the supported brokers running and wants to keep the option open. It does not fit a project that has moved off Yii2, or a team that needs guarantees about retries, priorities or delivery semantics beyond what the driver provides. Before adopting it, read UPGRADE.md and the CHANGELOG against the version you pin, confirm the broker you run is one of the supported drivers with its own console commands, and check the PHP 8.3 requirement against your runtime.

## FAQ

### Which queue backends does yii2-queue support?

The README lists queues based on DB, Redis, RabbitMQ, AMQP, Beanstalk, ActiveMQ and Gearman, and the repository description names DB, Redis, RabbitMQ, Beanstalk and Gearman. The development environment brings up MySQL, Postgres, Redis, RabbitMQ, Beanstalk, Gearman, ActiveMQ and LocalStack for SQS.

### How do I push a job and run a worker in yii2-queue?

A job is a class implementing the queue JobInterface, pushed with Yii::$app->queue->push. Workers use the yii queue/run command, which processes tasks until the queue is empty, or yii queue/listen, which launches a daemon that keeps querying the queue. Most drivers register these console commands automatically.

### How can I check whether a queued job has finished?

Push returns a message id, and the component offers isWaiting, isReserved and isDone for that id. They report whether the job is queued, whether a worker has reserved it, and whether it was executed, but there is no failed state and the job's own result is not returned.

### What PHP version does yii2-queue need?

The README marks PHP 8.3 as the minimum required version, and the install command is php composer.phar require --prefer-dist yiisoft/yii2-queue. The Makefile targets also default to PHP 8.3 for the Docker test environment.

### Can yii2-queue run a job later instead of immediately?

Yes. The delay method is applied before push, so a job that should run in five minutes is pushed with a delay of 5 * 60 seconds rather than being scheduled by an external scheduler.

## Sources

- [License: BSD-3-Clause](https://github.com/yiisoft/yii2-queue/blob/master/LICENSE)
- [Project website](http://www.yiiframework.com)
- [README](https://github.com/yiisoft/yii2-queue/blob/master/README.md)
- [Releases](https://github.com/yiisoft/yii2-queue/releases)
- [yiisoft/yii2-queue on GitHub](https://github.com/yiisoft/yii2-queue)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yiisoft-yii2-queue