message-handler.md

Message handler

If you are new to the concept of messages and handlers, read Messages and handlers: concepts first.

The simplest setup requires no configuration at all: create a dedicated class implementing Yiisoft\Queue\Message\MessageHandlerInterface and use its FQCN as the message type when pushing a message.

HandlerInterface implementation (without type mapping)

If your handler implements Yiisoft\Queue\Message\MessageHandlerInterface, you can use the class FQCN as the message type. The DI container resolves the handler automatically.

By default the yiisoft/di container resolves all FQCNs into corresponding class objects.

Message:

use Yiisoft\Queue\Message\Message;

final class RemoteFileMessage extends Message
{
    public function __construct(public readonly string $url) {}

    public static function fromData(string $type, bool|int|float|string|array|null $data): static
    {
        if (!is_array($data) || !is_string($data['url'] ?? null)) {
            throw new \InvalidArgumentException('Invalid data for ' . self::class . '.');
        }
        return new self($data['url']);
    }

    public function getType(): string
    {
        return \App\Queue\RemoteFileHandler::class;
    }

    public function getData(): array
    {
        return ['url' => $this->url];
    }
}

new RemoteFileMessage('https://...');

Handler:

final class RemoteFileHandler implements \Yiisoft\Queue\Message\MessageHandlerInterface
{
    public function handle(\Yiisoft\Queue\Message\MessageInterface $message): void
    {
        // Handle the message
    }
}

Config: Not needed.

Pros:

• Minimal configuration.
• Rename-safe within the same application (rename both the class and the message creation code together).
• Easy to unit-test the handler as a normal class.

Cons:

• Message types are PHP class names — works only when message creation and handler live in the same codebase.

Use when:

• Producer and consumer are the same application.
• You control message creation and can safely use FQCN as the message type.

When FQCN is not enough

When the producer is an external application or a different service, FQCN-based types create a hard dependency on PHP class names. In that case, use short stable message types mapped to callables in config.

See Message handler: advanced setup for all supported definition formats, pitfalls, and recommendations.