Guide improvements and bugfixes

Author: viktorprogger

docs/guide/en/channels.md

@@ -126,10 +126,18 @@ $queue = $provider->get('emails');
 ```
 
 ## Configuration with yiisoft/config
+ 
+ When using [yiisoft/config](https://github.com/yiisoft/config), channel configuration is stored in params under `yiisoft/queue.channels`.
 
-When using [yiisoft/config](https://github.com/yiisoft/config), channel configuration is stored in params under `yiisoft/queue.channels`.
+ By default, `QueueProviderInterface` is bound to `AdapterFactoryQueueProvider`.
+ That makes `yiisoft/queue.channels` a strict channel registry:
 
-It is a map:
+ - `QueueProviderInterface::has($channel)` checks whether the channel exists in definitions.
+ - `QueueProviderInterface::get($channel)` throws `ChannelNotFoundException` for unknown channels.
+
+ The same channel list is used by `queue:run` and `queue:listen-all` as the default set of channels to process.
+ 
+ It is a map:
 
 - key: channel name
 - value: adapter definition that should be resolved for that channel

docs/guide/en/configuration-with-config.md

@@ -9,13 +9,27 @@ If your project structure differs, put configuration into any params config file
 
 ## What you need to configure
 
-- Optionally: define default `\Yiisoft\Queue\Adapter\AdapterInterface` implementation.
-- And/or define channel-specific `AdapterInterface` implementations in the `channels` params key. See more about channels [here](./channels.md).
-- Define [message handlers](./message-handlers.md) in the `handlers` params key to be used with the `QueueWorker`.
+- Define queue channel adapter definitions in the `channels` params key. See more about channels [here](./channels.md).
+- Optionally: define [message handlers](./message-handler.md) in the `handlers` params key to be used with the `QueueWorker`.
 - Resolve other `\Yiisoft\Queue\Queue` dependencies (psr-compliant event dispatcher).
 
+By default, when using the DI config provided by this package, `QueueProviderInterface` is bound to `AdapterFactoryQueueProvider` and uses `yiisoft/queue.channels` as a strict channel registry.
+That means unknown channels are not accepted silently and `QueueProviderInterface::get()` will throw `ChannelNotFoundException`.
+The configured channel names are also used as the default channel list for `queue:run` and `queue:listen-all`.
+
+For development and testing you can start with the synchronous adapter.
+For production you must use a real backend adapter (AMQP, Kafka, SQS, etc.). If you do not have any preference, start with [yiisoft/queue-amqp](https://github.com/yiisoft/queue-amqp) and [RabbitMQ](https://www.rabbitmq.com/).
+
+The examples below use the synchronous adapter for brevity. In production, override `yiisoft/queue.channels` with an adapter definition from the backend adapter package you selected.
+
 ## Minimal configuration example
 
+If you use the handler class FQCN as the message handler name, no additional configuration is required.
+
+See [Message handler](./message-handler.md) for details and trade-offs.
+
+## Minimal configuration example (named handlers)
+
 ```php
 return [
     'yiisoft/queue' => [
@@ -35,11 +49,12 @@ return [
             'handler-name' => [FooHandler::class, 'handle'],
         ],
         'channels' => [
-            \Yiisoft\Queue\QueueInterface::DEFAULT_CHANNEL => \Yiisoft\Queue\Adapter\AdapterInterface::class,
+            \Yiisoft\Queue\QueueInterface::DEFAULT_CHANNEL => \Yiisoft\Queue\Adapter\SynchronousAdapter::class,
         ],
-        'middlewares-push' => [],
-        'middlewares-consume' => [],
-        'middlewares-fail' => [],
+        'middlewares-push' => [], // push middleware pipeline definition
+        'middlewares-consume' => [], // consume middleware pipeline definition
+        'middlewares-fail' => [], // consume failure handling middleware pipeline definition
     ],
 ];
 ```
+Middleware pipelines are discussed in detail [here](./middleware-pipelines.md).

docs/guide/en/console-commands.md

@@ -6,6 +6,9 @@ If you are using [yiisoft/config](https://github.com/yiisoft/config) and [yiisof
 
 If you are using [symfony/console](https://github.com/symfony/console) directly, you should register the commands manually.
 
+In [yiisoft/app](https://github.com/yiisoft/app) the `yii` console binary is provided out of the box.
+If you are using [yiisoft/console](https://github.com/yiisoft/console) or `symfony/console` without that template, invoke these commands the same way you invoke other console commands in your application.
+
 ## 1. Run queued messages and exit
 
 The command `queue:run` obtains and executes tasks until the queue is empty, then exits.  

docs/guide/en/message-handler.md

@@ -107,7 +107,6 @@ This way external producers never need to know your internal PHP class names.
 
 ## Common pitfalls and unsupported formats
 
-- A string definition is treated as a DI container ID first. If the container doesn't have such entry, it is resolved as a callable only when it is a valid PHP callable.
 - A class-string that is not resolvable via `$container->has()` will not be auto-instantiated.
 - [yiisoft/definitions](https://github.com/yiisoft/definitions) array format (like `['class' => ..., '__construct()' => ...]`) is **not** supported for handlers.
 

docs/guide/en/prerequisites-and-installation.md

@@ -5,6 +5,10 @@
 - PHP 8.1 or higher.
 - PCNTL extension for signal handling (optional, recommended for production use).
 
+If `ext-pcntl` is not installed, workers cannot handle OS signals (such as `SIGTERM`/`SIGINT`) gracefully.
+In practice it means a process manager may terminate a worker at any time, which can interrupt a job in the middle of execution.
+See [Loops](loops.md) for details.
+
 ## Installation
 
 Install the package with [Composer](https://getcomposer.org):

docs/guide/en/usage.md

@@ -48,8 +48,13 @@ $queue->push($message);
 
 To push a job into the queue that should run after 5 minutes:
 
+Delayed execution is implemented via a push middleware.
+The middleware must implement `\Yiisoft\Queue\Middleware\Push\Implementation\DelayMiddlewareInterface` and be provided by the adapter package you use.
+For example, the official AMQP adapter supports delays: <https://github.com/yiisoft/queue-amqp>
+
 ```php
-// TODO
+$delayMiddleware = $container->get(\Yiisoft\Queue\Middleware\Push\Implementation\DelayMiddlewareInterface::class);
+$queue->push($message, $delayMiddleware->withDelay(5 * 60));
 ```
 
 **Important:** Not every adapter (such as synchronous adapter) supports delayed execution.