configuration-with-config.md

Configuration with yiisoft/config

If you are using yiisoft/config (i.e. installed with yiisoft/app or yiisoft/app-api), you'll find out this package has some defaults in the common and params configurations saving your time.

Where to put the configuration

In yiisoft/app / yiisoft/app-api templates you typically add or adjust configuration in config/params.php. If your project structure differs, put configuration into any params config file that is loaded by yiisoft/config.

When your message type equals the FQCN of a handler class that implements Yiisoft\Queue\Message\MessageHandlerInterface, nothing else has to be configured: the DI container resolves the class automatically. See Message handler for details and trade-offs.

Advanced applications eventually need the following tweaks:

• Queue names — configure queue/back-end per logical queue name via yiisoft/queue.queues config when you need to parallelize message handling or send some of them to a different application.

• Named handlers or callable definitions — map a short message type to a callable in yiisoft/queue.handlers config when another application is the message producer and you cannot use FQCN as message type.

• Message class map — map message types to specific message classes so that MessageSerializerInterface::unserialize() reconstructs the original typed object instead of falling back to GenericMessage. Configure via yiisoft/queue.messages:

  return [
      'yiisoft/queue' => [
          'messages' => [
              'send-email' => SendEmailMessage::class,
              'download-file' => DownloadFileMessage::class,
          ],
      ],
  ];

  When a type is not present in the map, GenericMessage is used as a fallback.

• Middleware pipelines — adjust push/consume/failure behavior: collect metrics, modify messages, and so on. See Middleware pipelines for details.

If you don't have a broker yet (for development, testing, or as a stepping stone before introducing async processing), you can run the queue in synchronous mode. For real asynchronous processing pick a backend adapter (AMQP, Kafka, SQS, etc.). If you do not have any preference, it's simpler to start with yiisoft/queue-amqp and RabbitMQ.