Docs enhancements

Author: viktorprogger

docs/guide/en/README.md

@@ -1,46 +1,36 @@
-# Yii Queue
+# Yii Queue documentation map
 
-An extension for running tasks asynchronously via queues.
-
-## Getting started
+## Install and configure
 
 - [Prerequisites and installation](prerequisites-and-installation.md)
 - [Configuration with yiisoft/config](configuration-with-config.md)
-- [Manual configuration](configuration-manual.md)
-
-- [Usage basics](usage.md)
-- [Workers](worker.md)
-- [Console commands](console-commands.md)
-
-## Adapters
-
 - [Adapter list](adapter-list.md)
 - [Synchronous adapter](adapter-sync.md)
-
-## Core concepts
-
 - [Queue names](queue-names.md)
-- [Message handler](message-handler.md)
-- [Envelopes](envelopes.md)
-- [Middleware pipelines](middleware-pipelines.md)
-- [Loops](loops.md)
 
-## Interoperability
+## Build and run jobs
 
-- [Producing messages from external systems](consuming-messages-from-external-systems.md)
+- [Usage basics](usage.md)
+- [Messages and handlers: concepts](messages-and-handlers.md)
+- [Message handler](message-handler-simple.md)
+- [Console commands](console-commands.md)
+- [Job status](job-status.md)
 
 ## Reliability and visibility
 
 - [Errors and retryable jobs](error-handling.md)
-- [Job status](job-status.md)
+- [Envelopes](envelopes.md)
 - [Yii Debug integration](debug-integration.md)
 
-## Production and optimization
+## Production readiness
 
 - [Best practices](best-practices.md)
 - [Running workers in production (systemd and Supervisor)](process-managers.md)
-- [Performance tuning](performance-tuning.md)
 
-## Migration from Yii2
+## Migration
 
 - [Migrating from `yii2-queue`](migrating-from-yii2-queue.md)
+
+## Advanced topics
+
+Open the [advanced documentation map](advanced-map.md) if you build custom middleware, adapters, queue providers, or tooling.

docs/guide/en/advanced-map.md

@@ -0,0 +1,49 @@
+# Advanced documentation map
+
+Use this index when you need to customize internals: custom middleware, adapters, queue providers, tooling, or diagnostics.
+
+## Configuration and infrastructure
+
+- [Manual configuration without yiisoft/config](configuration-manual.md) — wiring queues, workers, and middleware factories without `yiisoft/config`.
+- [Queue provider registry](#queue-provider-registry) — selecting and extending adapter factories.
+- [Loops and worker processes](loops.md) — implementing custom runners, heartbeat hooks, and graceful shutdown (requires `pcntl`).
+- [Worker internals](worker.md) — dependency resolution and middleware stacks within `WorkerInterface`.
+- [Performance tuning](performance-tuning.md) — profiling handlers, envelopes, and adapters.
+
+## Middleware, envelopes, and handlers
+
+- [Middleware pipelines deep dive](middleware-pipelines.md) — dispatcher lifecycle, request mutations, and per-pipeline contracts.
+- [Callable definitions and middleware factories](callable-definitions-extended.md) — container-aware definitions for middleware factories.
+- [Error handling](error-handling.md#failure-pipeline-overview) — end-to-end flow of the failure pipeline.
+- [Custom failure middleware](error-handling.md#how-to-create-a-custom-failure-middleware) — implementing `MiddlewareFailureInterface`.
+- [Envelope metadata and stack reconstruction](envelopes.md#metadata-and-envelope-stacking) — stack resolution and metadata merging.
+- [FailureEnvelope usage](error-handling.md#failureenvelope) — retry metadata semantics.
+- [Handler resolver pipeline](message-handler.md#resolver-pipeline) — alternative handler lookup strategies.
+
+## Queue adapters and interoperability
+
+- [Custom queue provider implementations](queue-names-advanced.md#extending-the-registry) — bespoke selection logic, tenant registries, and fallback strategies.
+- [Consuming messages from external systems](consuming-messages-from-external-systems.md) — contract for third-party producers.
+- [Adapter internals](adapter-list.md#available-adapters) — extend or swap backend adapters.
+
+## Tooling, diagnostics, and storage
+
+- [Yii Debug collector internals](debug-integration-advanced.md) — collector internals, proxies, and manual wiring.
+- [Job status storage extensions](job-status.md#extend-storage) — persisting custom metadata or drivers.
+- [Extending queue processes and supervisors](process-managers.md#custom-supervisors) — custom supervisor hooks and graceful shutdown integration.
+
+## Internals and contribution
+
+- [Internals guide](../../internals.md) — local QA tooling (PHPUnit, Infection, Psalm, Rector, ComposerRequireChecker).
+
+## Queue provider registry
+
+When multiple queue names share infrastructure, rely on `QueueProviderInterface`:
+
+- A queue name is passed to `QueueProviderInterface::get($queueName)` and resolved into a configured `QueueInterface` instance.
+- Providers typically construct adapters lazily via [`yiisoft/factory`](https://github.com/yiisoft/factory) and call `AdapterInterface::withChannel($channel)` to switch broker-specific channels.
+- Default implementation (`AdapterFactoryQueueProvider`) enforces a strict registry defined in `yiisoft/queue.channels`. Unknown names throw `ChannelNotFoundException`.
+- Alternative providers include:
+  - `PrototypeQueueProvider` — clones a base queue/adapter, switching only the channel name (useful when all queues share infrastructure but risks typos).
+  - `CompositeQueueProvider` — aggregates multiple providers and selects the first that knows the queue name.
+- Implement `QueueProviderInterface` to introduce custom registries or fallback strategies, then register the implementation in DI.

docs/guide/en/best-practices.md

@@ -263,7 +263,7 @@ $queue->push(new Message(
 
 #### More info
 
-See [Message handler](message-handler.md) for details.
+See [Message handler](message-handler-simple.md) for details.
 
 ## Monitoring and observability
 

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

@@ -7,53 +7,13 @@ If you are using [yiisoft/config](https://github.com/yiisoft/config) (i.e. insta
 In [yiisoft/app](https://github.com/yiisoft/app) / [yiisoft/app-api](https://github.com/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](https://github.com/yiisoft/config).
 
-## What you need to configure
+When your message uses a handler class that implements `Yiisoft\Queue\Message\MessageHandlerInterface` and the handler name equals its FQCN, nothing else has to be configured: the DI container resolves the class automatically. See [Message handler: simple setup](message-handler-simple.md) for details and trade-offs.
 
-- Define queue name adapter definitions in the `channels` params key. See more about queue names [here](./queue-names.md).
-- Optionally: define [message handlers](./message-handler.md) in the `handlers` params key to be used with the `QueueWorker`.
+Advanced applications eventually need the following tweaks:
 
-By default, when using the DI config provided by this package, `QueueProviderInterface` is bound to `AdapterFactoryQueueProvider` and uses `yiisoft/queue.channels` as a strict queue name registry.
-That means unknown queue names are not accepted silently and `QueueProviderInterface::get()` will throw `ChannelNotFoundException`.
-The configured queue names are also used as the default queue name list for `queue:run` and `queue:listen-all`.
+- **Channels** — configure queue/back-end per logical queue name via [`yiisoft/queue.channels` config](queue-names.md) when you need to parallelize message handling or send some of them to a different application.
+- **Named handlers or callable definitions** — map a short handler name to a callable in [`yiisoft/queue.handlers` config](message-handler.md) when another application is the message producer and you cannot use FQCN as the handler name.
+- **Middleware pipelines** — adjust push/consume/failure behavior: collect metrics, modify messages, and so on. See [Middleware pipelines](middleware-pipelines.md) for details.
 
 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' => [
-        'handlers' => [
-            'handler-name' => [FooHandler::class, 'handle'],
-        ],
-    ],
-];
-```
-
-## Full configuration example
-
-```php
-return [
-    'yiisoft/queue' => [
-        'handlers' => [
-            'handler-name' => [FooHandler::class, 'handle'],
-        ],
-        'channels' => [
-            \Yiisoft\Queue\QueueInterface::DEFAULT_CHANNEL => \Yiisoft\Queue\Adapter\SynchronousAdapter::class,
-        ],
-        '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).
+For production you have to use a [real backend adapter](adapter-list.md) (AMQP, Kafka, SQS, etc.). If you do not have any preference, it's simpler to start with [yiisoft/queue-amqp](https://github.com/yiisoft/queue-amqp) and [RabbitMQ](https://www.rabbitmq.com/).

docs/guide/en/consuming-messages-from-external-systems.md

@@ -1,4 +1,4 @@
-# Producing messages from external systems
+# Consuming messages from external systems
 
 This guide explains how to publish messages to a queue backend (RabbitMQ, Kafka, SQS, etc.) from *external producers* (including non-PHP services) so that `yiisoft/queue` consumers can correctly deserialize and process these messages.
 
@@ -16,7 +16,7 @@ So, external systems should produce the **same payload format** that your consum
 
 `yiisoft/queue` resolves a handler by message handler name (`MessageInterface::getHandlerName()`).
 
-For external producers, you should not rely on PHP FQCN handler names. Prefer a stable short name and map it in the consumer application configuration (see [Message handler](message-handler.md)).
+For external producers, you should not rely on PHP FQCN handler names. Prefer a stable short name and map that name to a handler callable in the consumer application configuration (see [Message handler](message-handler.md)).
 
 Example mapping:
 
@@ -70,7 +70,7 @@ Full example:
 
 ### Notes about `meta`
 
-The `meta` key is a general-purpose metadata container (for example, tracing, correlation, tenant information). External systems may populate it, and the consumer-side application or middleware may also read, add, or override keys as needed. However, it's not recommended, as it highly depends on the consumer-side application code.
+The `meta` key is a general-purpose metadata container (for example, tracing, correlation, tenant information). The consumer-side application or middleware may read, add, or override keys as needed. Populating `meta` from external producers is possible but not recommended: the accepted keys and their semantics are entirely defined by the consumer application, so any contract must be maintained manually.
 
 ## 3. Data encoding rules
 

docs/guide/en/debug-integration-advanced.md

@@ -0,0 +1,46 @@
+# Advanced Yii Debug integration
+
+Use this guide when you need to understand which events are tracked by the queue collector, how proxy services operate, and how to wire the collector manually.
+
+## What is collected
+
+The integration is based on `Yiisoft\Queue\Debug\QueueCollector` and captures:
+
+- Pushed messages grouped by queue name (including middleware definitions passed to `push()`).
+- Job status checks performed via `QueueInterface::status()`.
+- Messages processed by a worker grouped by queue name.
+
+## How it works
+
+The collector is enabled by registering it in Yii Debug and wrapping tracked services with proxy implementations.
+
+Out of the box (see this package's `config/params.php`), the following services are intercepted:
+
+- `Yiisoft\Queue\Provider\QueueProviderInterface` is wrapped with `Yiisoft\Queue\Debug\QueueProviderInterfaceProxy`. The proxy decorates returned queues with `Yiisoft\Queue\Debug\QueueDecorator` so that `push()` and `status()` calls are reported to the collector.
+- `Yiisoft\Queue\Worker\WorkerInterface` is wrapped with `Yiisoft\Queue\Debug\QueueWorkerInterfaceProxy` to record message processing events.
+
+To see data in the debug panel you must obtain `QueueProviderInterface` and `WorkerInterface` from the DI container so that the proxies remain in effect.
+
+## Manual configuration
+
+If you do not rely on the defaults supplied via [yiisoft/config](https://github.com/yiisoft/config), configure the collector and proxies explicitly:
+
+```php
+use Yiisoft\Queue\Debug\QueueCollector;
+use Yiisoft\Queue\Debug\QueueProviderInterfaceProxy;
+use Yiisoft\Queue\Debug\QueueWorkerInterfaceProxy;
+use Yiisoft\Queue\Provider\QueueProviderInterface;
+use Yiisoft\Queue\Worker\WorkerInterface;
+
+return [
+    'yiisoft/yii-debug' => [
+        'collectors' => [
+            QueueCollector::class,
+        ],
+        'trackedServices' => [
+            QueueProviderInterface::class => [QueueProviderInterfaceProxy::class, QueueCollector::class],
+            WorkerInterface::class => [QueueWorkerInterfaceProxy::class, QueueCollector::class],
+        ],
+    ],
+];
+```

docs/guide/en/debug-integration.md

@@ -2,54 +2,6 @@
 
 This package provides an integration with [yiisoft/yii-debug](https://github.com/yiisoft/yii-debug).
 
-When debug is enabled, it collects queue-related information and shows it in the Yii Debug panel.
+When Yii Debug is enabled, the queue collector adds a panel that shows pushed messages, job status checks, and worker activity.
 
-## What is collected
-
-The integration is based on `Yiisoft\Queue\Debug\QueueCollector`.
-
-It collects:
-
-- Pushed messages grouped by queue name (including middleware definitions passed to `push()`).
-- Job status checks performed via `QueueInterface::status()`.
-- Messages processed by a worker grouped by queue name.
-
-## How it works
-
-The details below are optional. You can skip them if you only need to enable the panel and see collected data.
-
-The integration is enabled by registering the collector and wrapping tracked services with proxy implementations.
-
-In this package defaults (see `config/params.php`), the following services are tracked:
-
-- `Yiisoft\Queue\Provider\QueueProviderInterface` is wrapped with `Yiisoft\Queue\Debug\QueueProviderInterfaceProxy`.
-  The proxy decorates returned queues with `Yiisoft\Queue\Debug\QueueDecorator` to collect `push()` and `status()` calls.
-- `Yiisoft\Queue\Worker\WorkerInterface` is wrapped with `Yiisoft\Queue\Debug\QueueWorkerInterfaceProxy` to collect message processing.
-
-Because of that, to see data in debug you should obtain `QueueProviderInterface` / `WorkerInterface` from the DI container.
-
-## Configuration
-
-If you use [yiisoft/config](https://github.com/yiisoft/config) and the configuration plugin, these defaults are loaded automatically from this package.
-
-Otherwise, you can configure it manually in your params configuration:
-
-```php
-use Yiisoft\Queue\Debug\QueueCollector;
-use Yiisoft\Queue\Debug\QueueProviderInterfaceProxy;
-use Yiisoft\Queue\Debug\QueueWorkerInterfaceProxy;
-use Yiisoft\Queue\Provider\QueueProviderInterface;
-use Yiisoft\Queue\Worker\WorkerInterface;
-
-return [
-    'yiisoft/yii-debug' => [
-        'collectors' => [
-            QueueCollector::class,
-        ],
-        'trackedServices' => [
-            QueueProviderInterface::class => [QueueProviderInterfaceProxy::class, QueueCollector::class],
-            WorkerInterface::class => [QueueWorkerInterfaceProxy::class, QueueCollector::class],
-        ],
-    ],
-];
-```
+If you use [yiisoft/config](https://github.com/yiisoft/config) together with this package, the debug collector is registered automatically. For manual configuration snippets and proxy wiring details, see [Advanced Yii Debug integration](debug-integration-advanced.md).

docs/guide/en/message-handler-simple.md

@@ -0,0 +1,53 @@
+# Message handler
+
+> If you are new to the concept of messages and handlers, read [Messages and handlers: concepts](messages-and-handlers.md) first.
+
+The simplest setup requires no configuration at all: create a dedicated class implementing `Yiisoft\Queue\Message\MessageHandlerInterface` and use its FQCN as the handler name when pushing a message.
+
+## HandlerInterface implementation (without name mapping)
+
+If your handler implements `Yiisoft\Queue\Message\MessageHandlerInterface`, you can use the class FQCN as the message handler name. The DI container resolves the handler automatically.
+
+> By default the [yiisoft/di](https://github.com/yiisoft/di) container resolves all FQCNs into corresponding class objects.
+
+**Message**:
+
+```php
+new \Yiisoft\Queue\Message\Message(\App\Queue\RemoteFileHandler::class, ['url' => '...']);
+```
+
+**Handler**:
+
+```php
+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 class and producer together).
+- Easy to unit-test the handler as a normal class.
+
+**Cons**:
+
+- Couples message names to PHP class names.
+- Requires producer and consumer to share the same naming contract (typically the same app).
+
+**Use when**:
+
+- Producer and consumer are the same application.
+- You control message creation and can safely use FQCN as the handler name.
+
+## When FQCN is not enough
+
+When the producer is an external application or a different service, FQCN-based names create a hard dependency on PHP class names. In that case, use short stable handler names mapped to callables in config.
+
+See [Message handler: named handlers and advanced formats](message-handler.md) for all supported definition formats, pitfalls, and recommendations.