A framework-agnostic PHP queue library for running tasks asynchronously, best used with Yii3 applications.
- PHP 8.1 - 8.5.
- PCNTL extension for signal handling (optional, recommended for production use).
The package could be installed with Composer:
composer require yiisoft/queue
For production use, you should install an adapter package that matches your message broker (AMQP, Kafka, NATS, and others). See the adapter list and follow the adapter-specific documentation for installation and configuration details.
If you don't have an external broker — whether for development, testing, or because you want to design around
QueueProducerInterfacefrom day one and add a real broker later — you can run the queue in synchronous mode usingSyncQueueProducerinstead ofAsyncQueueProducer. In this mode messages are processed immediately in the same process, so it won't provide true async execution, but the code stays the same when you switch to a real adapter.
Define a message class for the work to be done — a simple value object with typed properties:
use Yiisoft\Queue\Message\Message; final class DownloadFileMessage extends Message { public const TYPE = 'download-file'; public function __construct( public readonly string $url, public readonly string $destinationPath, ) {} public static function fromPayload(string $type, bool|int|float|string|array|null $payload): static { if ($type !== self::TYPE) { throw new \InvalidArgumentException("Expected type \"" . self::TYPE . "\", got \"$type\"."); } if (!is_array($payload) || !is_string($payload['url'] ?? null) || !is_string($payload['destinationPath'] ?? null) ) { throw new \InvalidArgumentException('Invalid data for ' . self::class . '.'); } return new self($payload['url'], $payload['destinationPath']); } public function getType(): string { return self::TYPE; } public function getPayload(): array { return ['url' => $this->url, 'destinationPath' => $this->destinationPath]; } }
Then create a handler that processes it:
use Yiisoft\Queue\Message\Handler\HandlerInterface; use Yiisoft\Queue\Message\MessageInterface; final readonly class RemoteFileHandler implements HandlerInterface { public function __construct( private FileDownloader $downloader, private FileProcessor $processor, ) {} public function handle(MessageInterface $message): void { assert($message instanceof DownloadFileMessage); $localPath = $this->downloader->download($message->url, $message->destinationPath); $this->processor->process($localPath); } }
Configuration with yiisoft/config
If you use yiisoft/app or yiisoft/app-api
Add queue configuration to your application $params config. In yiisoft/app/yiisoft/app-api templates it's typically the config/params.php file.
If your project structure differs, put it into any params config file that is loaded by yiisoft/config.
Minimal configuration example:
return [ 'yiisoft/queue' => [ 'handlers' => [ DownloadFileMessage::TYPE => RemoteFileHandler::class, ], ], ];
Advanced configuration with yiisoft/config
For setting up all classes manually, see the Manual configuration guide.
To send a message to the queue, get the queue instance and call push(). Typically the queue is injected as a dependency:
use Yiisoft\Queue\QueueProducerInterface; final readonly class Foo { public function __construct(private QueueProducerInterface $queue) {} public function bar(): void { $this->queue->push(new DownloadFileMessage( url: 'https://example.com/file-path.csv', destinationPath: '/tmp/file-path.csv', )); } }
By default, Yii Framework uses yiisoft/yii-console to run CLI commands. If you installed yiisoft/app or yiisoft/app-api, you can run the queue worker with queue:consume:
./yii queue:consume --once # Handle all existing messages in the queue ./yii queue:consume [queueName] # Start a daemon listening for new messages permanently from the specified queue ./yii queue:consume --all [queueName [queueName2 [...]]] # Start a daemon listening for new messages permanently from all consumer-capable queues or specified list of queues (use with caution in production, recommended for dev only)
See Console commands for more details.
Producers use Yiisoft\Queue\QueueProducerInterface (push(), status(), getQueueName()); consumers use Yiisoft\Queue\QueueConsumerInterface (run(), listen()). See capability configuration for the strict role map used when named queues are configured.
In case you're running the queue in synchronous mode (no adapter),
queue:consumelogs an info message and exits. The messages are processed immediately when pushed.
If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.
This package follows semantic versioning.
The /stubs directory is intended for testing purposes only and must not be used in production code.
Any changes there, including breaking ones, are always released as a patch version.
The Yii Queue is free software. It is released under the terms of the BSD License.
Please see LICENSE for more information.
Maintained by Yii Software.