An extension for running tasks asynchronously via queues.

• 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.

For development and testing, you can start without an external broker using the built-in SynchronousAdapter. This adapter processes messages immediately in the same process, so it won't provide true async execution, but it's useful for getting started and writing tests.

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' => [
            'message-type' => [FooHandler::class, 'handle'],
        ],
    ],
];

Advanced configuration with yiisoft/config

For setting up all classes manually, see the Manual configuration guide.

You need to create a handler class that will process the queue messages. The most simple way is to implement the MessageHandlerInterface. Let's create an example for remote file processing:

use Yiisoft\Queue\Message\MessageInterface;
use Yiisoft\Queue\Message\MessageHandlerInterface;

final readonly class RemoteFileHandler implements MessageHandlerInterface
{
    // These dependencies will be resolved on handler creation by the DI container
    public function __construct(
        private FileDownloader $downloader,
        private FileProcessor $processor,
    ) {}

    // Every received message will be processed by this method
    public function handle(MessageInterface $downloadMessage): void
    {
        $url = $downloadMessage->getData()['url'];
        $localPath = $this->downloader->download($url);
        $this->processor->process($localPath);
    }
}

To send a message to the queue, you need to get the queue instance and call the push() method. Typically, with Yii Framework you'll get a Queue instance as a dependency of a service.

final readonly class Foo {
    public function __construct(private QueueInterface $queue) {}

    public function bar(): void
    {
        $this->queue->push(new Message(
            // The first parameter is the message type used to resolve the handler which will process the message
            RemoteFileHandler::class,
            // The second parameter is the data that will be passed to the handler.
            // It should be serializable to JSON format
            ['url' => 'https://example.com/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 one of these two commands:

./yii queue:run # Handle all existing messages in the queue
./yii queue:listen [queueName] # Start a daemon listening for new messages permanently from the specified queue
./yii queue:listen-all [queueName [queueName2 [...]]] # Start a daemon listening for new messages permanently from all queues or specified list of queues (use with caution in production, recommended for dev only)

See Console commands for more details.

In case you're using the SynchronousAdapter for development purposes, you should not use these commands, as you have no asynchronous processing available. The messages are processed immediately when pushed.

• Guide
• Internals

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.

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.