Documentation #250

viktorprogger · 2025-12-13T10:21:35Z

Q	A
Is bugfix?	✔️
New feature?	❌
Breaks BC?	❌

codecov · 2025-12-13T13:20:23Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.88%. Comparing base (493a753) to head (4fe7321).

Files with missing lines	Patch %	Lines
src/Worker/Worker.php	83.33%	8 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #250      +/-   ##
============================================
- Coverage     98.59%   97.88%   -0.72%     
- Complexity      356      362       +6     
============================================
  Files            47       47              
  Lines           927      945      +18     
============================================
+ Hits            914      925      +11     
- Misses           13       20       +7

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

samdark · 2025-12-14T10:39:15Z

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

+
+- Optionally: define default `\Yiisoft\Queue\Adapter\AdapterInterface` implementation.
+- And/or define channel-specific `AdapterInterface` implementations in the `channels` params key to be used
+  with the [queue provider](usage.md#different-queue-channels).


There's nothing in usage.md about queue provider and there's no such anchor as well.

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

docs/guide/en/message-handler.md

README.md

Co-authored-by: Alexander Makarov <[email protected]>

…elated guides

Copilot

Pull request overview

This pull request is marked as a bugfix and includes significant documentation improvements, code refactoring, and a critical bug fix. The main changes involve integrating CallableFactory into the Worker class to simplify handler resolution, fixing a bug in the JSON message serializer, adding comprehensive documentation, and adding a command alias.

Key changes:

Integration of CallableFactory into Worker for unified callable resolution
Bug fix in JsonMessageSerializer where $payload['meta'] was incorrectly accessed instead of $meta
Extensive documentation added covering queue channels, message handlers, middleware pipelines, error handling, and more
Command alias queue:listen-all added to replace the typo queue:listen:all

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Unit/WorkerTest.php	Added new test case for object method callable definitions and updated tests to use CallableFactory parameter
tests/Unit/Middleware/CallableFactoryTest.php	Major refactoring with data providers for comprehensive testing of callable factory scenarios
tests/TestCase.php	Added CallableFactory parameter to worker creation
tests/Integration/MiddlewareTest.php	Added CallableFactory parameter to test setup
tests/Integration/MessageConsumingTest.php	Added CallableFactory instantiation and parameter in worker setup
tests/Benchmark/QueueBench.php	Added CallableFactory parameter to worker constructor
src/Worker/Worker.php	Integrated CallableFactory for unified handler resolution, simplified handler caching logic
src/Middleware/CallableFactory.php	Enhanced to support Closure detection, object method definitions, and improved validation
src/Message/JsonMessageSerializer.php	Bug fix: corrected variable reference from `$payload['meta']` to `$meta`
src/Command/ListenAllCommand.php	Added command alias 'queue:listen:all' for backward compatibility
docs/guide/en/worker.md	Rewritten to focus on starting workers and supervisor configuration
docs/guide/en/usage.md	Expanded with queue channels, delayed execution, job status examples
docs/guide/en/producing-messages-from-external-systems.md	New comprehensive guide for external message producers
docs/guide/en/prerequisites-and-installation.md	New installation and requirements guide
docs/guide/en/middleware-pipelines.md	New detailed middleware pipeline documentation
docs/guide/en/message-handler.md	New guide explaining handler definition formats and configuration
docs/guide/en/loops.md	New documentation on loop interface and signal handling
docs/guide/en/job-status.md	New guide on job status tracking
docs/guide/en/error-handling.md	Significantly expanded with step-by-step failure handling flow
docs/guide/en/envelopes.md	New documentation on envelope pattern and metadata handling
docs/guide/en/debug-integration.md	New guide for Yii Debug integration
docs/guide/en/console-commands.md	New comprehensive console commands reference
docs/guide/en/configuration-with-config.md	New configuration guide for yiisoft/config users
docs/guide/en/configuration-manual.md	New manual configuration guide with examples
docs/guide/en/channels.md	New detailed guide on queue channels concept and configuration
docs/guide/en/callable-definitions-extended.md	New guide explaining extended callable definition formats
docs/guide/en/README.md	Restructured guide index with better organization
config/params.php	Added 'queue:listen-all' command alias
README.md	Major rewrite with quick start guide and improved structure

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T19:59:07Z

docs/guide/en/callable-definitions-extended.md

@@ -0,0 +1,100 @@
+# Callable Definitions Extended
+
+Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.  


The word "Сallable" starts with a Cyrillic character 'С' (U+0421) instead of the Latin 'C' (U+0043). This should be "Callable" with a Latin C.

Suggested change

Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.

Callable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.

Copilot · 2026-01-07T19:59:08Z

README.md

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

 ```php
-class FileDownloader
+use Yiisoft\Queue\Handler\HandleInterface;
+use Yiisoft\Queue\Message\MessageInterface;
+
+final readonly class RemoteFileHandler implements HandleInterface


The documentation references HandleInterface but the actual interface in the codebase is MessageHandlerInterface (located at Yiisoft\Queue\Message\MessageHandlerInterface). The namespace and interface name should be corrected.

Copilot · 2026-01-07T19:59:08Z

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

+
+### Notes about `meta`
+
+The `meta` key is used by `yiisoft/queue` for internal processing (like tracing and correlation) and should not be set by external systems.


The documentation states that the meta key "should not be set by external systems" on line 73, but earlier on lines 41 and 64-67 it shows meta as an optional parameter in the JSON format. This is contradictory. Either external systems can provide metadata (in which case the warning should be removed or modified), or they shouldn't (in which case the examples and format description should be updated to clarify that meta is for internal use only and will be ignored or overwritten).

Suggested change

The `meta` key is used by `yiisoft/queue` for internal processing (like tracing and correlation) and should not be set by external systems.

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.

Copilot · 2026-01-07T19:59:08Z

README.md

-You can declare error handling a middleware pipeline in the `FailureMiddlewareDispatcher`, either in the constructor, or in the `withMiddlewares()` method. If you use [yiisoft/config](yiisoft/config), you can add middleware to the `middlewares-fail` key of the `yiisoft/queue` array in the `params`.
-
-See [error handling docs](docs/guide/error-handling.md) for details.
+> In case you're using the `SynchronosAdapter` for development purposes, you should not use these commands, as you have no asynchronous processing available. The messages are processed immediately when pushed.


Typo: "SynchronosAdapter" should be "SynchronousAdapter" (missing 'u' before 's').

Suggested change

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

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

Copilot · 2026-01-07T19:59:09Z

README.md


-To use this feature, you have to create a middleware class, which implements `MiddlewarePushInterface`, and
-return a modified `PushRequest` object from the `processPush` method:
+By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/yii-console) to run CLI commands. If you installed [yiisoft/app](https://github.com/yiisoft/app) or [yiisoft/app-api](https://github.com/yiisoft/app-api), you can run the queue worker with on of these two commands:


Typo: "on of these two commands" should be "one of these two commands".

Suggested change

By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/yii-console) to run CLI commands. If you installed [yiisoft/app](https://github.com/yiisoft/app) or [yiisoft/app-api](https://github.com/yiisoft/app-api), you can run the queue worker with on of these two commands:

By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/yii-console) to run CLI commands. If you installed [yiisoft/app](https://github.com/yiisoft/app) or [yiisoft/app-api](https://github.com/yiisoft/app-api), you can run the queue worker with one of these two commands:

samdark · 2026-01-07T20:05:57Z

docs/guide/en/callable-definitions-extended.md

@@ -0,0 +1,100 @@
+# Callable Definitions Extended
+
+Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.  


The sentence isn't clear. I read it as "callable definitions extend native PHP callables so there are two types of definitions because of that".

samdark · 2026-01-07T20:06:41Z

docs/guide/en/callable-definitions-extended.md

+# Callable Definitions Extended
+
+Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.  
+It is used across the package to convert configuration definitions into real callables.


It = injector or container?

samdark · 2026-01-07T20:07:06Z

docs/guide/en/callable-definitions-extended.md

+
+## Type 1: Native PHP callable
+
+When you define a callable in a such manner, they are not modified in any way and are called as is. An only difference is that you can define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.  


Which "such manner"? Do you mean native PHP callable?

What are they who are not modified? Callables? Parameters?

samdark · 2026-01-07T20:09:14Z

docs/guide/en/callable-definitions-extended.md

+
+- **Closure (lambda function)**. It may be static. Example:
+  ```php
+  $callable = static function(Update $update) {


What is Update here?

samdark · 2026-01-07T20:09:40Z

docs/guide/en/callable-definitions-extended.md

+
+## Type 2: Callable definition extensions (via container)
+
+Under the hood, this extension behaves exactly like the **Type 1** ones. But there is a major difference too:


Which "this extension"?

What's "type 1"?

samdark · 2026-01-07T20:30:26Z

docs/guide/en/console-commands.md

+yii queue:listen-all [channel1 [channel2 [...]]] --pause=1 --maximum=0
+```
+
+> The command alias `queue:listen:all` is deprecated and will be removed in `1.0.0`, since it was a typo.


Should be removed before release. Let's create an issue for it and for the actual alias. Or we can remove it right away. There was no release yet so there's no backwards compatibility promise yet.

samdark · 2026-01-07T20:32:48Z

docs/guide/en/debug-integration.md

+## How it works
+
+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.


That looks like internal info. Does the end user need to know these details? Same for many docs in the guide.

samdark · 2026-01-07T20:35:05Z

docs/guide/en/error-handling.md

-## Configuration
+## When failure handling is triggered
+
+Failure handling is triggered only when message processing throws a `Throwable`.


How about PHP notices or warnings or errors?

samdark · 2026-01-07T20:38:32Z

docs/guide/en/error-handling.md

+
+ Let's see the built-in defaults.
+
+ ### [SendAgainMiddleware](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php)


I don't think such links will work well when rendering the guide.

samdark · 2026-01-07T20:47:19Z

src/Worker/Worker.php

+        try {
+            $handler = $this->getHandler($name);
+        } catch (InvalidCallableConfigurationException $exception) {
+            throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist', $name), 0, $exception);


Suggested change

throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist', $name), 0, $exception);

throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist.', $name), 0, $exception);

viktorprogger and others added 2 commits December 13, 2025 15:20

Start docs refining

745b353

Apply fixes from StyleCI

eb27a90

viktorprogger changed the title ~~Start docs refining~~ Documentation Dec 13, 2025

samdark reviewed Dec 14, 2025

View reviewed changes

viktorprogger and others added 13 commits December 18, 2025 08:58

Apply suggestions from code review

ac1a2f8

Co-authored-by: Alexander Makarov <[email protected]>

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

1fb3057

Co-authored-by: Alexander Makarov <[email protected]>

Add links to mentioned packages

91bb7cf

Continue writing docs

2feaf14

Document Yii Debug integration

604f2c0

Fix queue:listen-all command name

aee4f72

Prerequisites and installation in the guide

7821be0

Middleware pipelines in the guide

4fe7321

Add comprehensive documentation for callable definitions and update r…

23e7997

…elated guides

Improve the channels.md guide

ae5867a

Remove redundant info from the main readme

f2e7eff

Guide improvements and bugfixes

c598caf

Merge two different failure handling guides

0f05e07

viktorprogger force-pushed the docs branch from bbc2707 to 0f05e07 Compare January 7, 2026 14:58

Apply Rector changes (CI)

dd3ae30

viktorprogger marked this pull request as ready for review January 7, 2026 15:19

samdark requested a review from Copilot January 7, 2026 19:50

Copilot started reviewing on behalf of samdark January 7, 2026 19:50 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

samdark reviewed Jan 7, 2026

View reviewed changes

		@@ -0,0 +1,100 @@
		# Callable Definitions Extended

		Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.

	Сallable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.
	Callable definitions in `yiisoft/queue` extend [native PHP callables](https://www.php.net/manual/en/language.types.callable.php). That means, there are two types of definitions. Nevertheless, each of them may define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.


		### Notes about `meta`

		The `meta` key is used by `yiisoft/queue` for internal processing (like tracing and correlation) and should not be set by external systems.

	The `meta` key is used by `yiisoft/queue` for internal processing (like tracing and correlation) and should not be set by external systems.
	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.

	> In case you're using the `SynchronosAdapter` for development purposes, you should not use these commands, as you have no asynchronous processing available. The messages are processed immediately when pushed.
	> 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.

	By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/yii-console) to run CLI commands. If you installed [yiisoft/app](https://github.com/yiisoft/app) or [yiisoft/app-api](https://github.com/yiisoft/app-api), you can run the queue worker with on of these two commands:
	By default, Yii Framework uses [yiisoft/yii-console](https://github.com/yiisoft/yii-console) to run CLI commands. If you installed [yiisoft/app](https://github.com/yiisoft/app) or [yiisoft/app-api](https://github.com/yiisoft/app-api), you can run the queue worker with one of these two commands:


		## Type 1: Native PHP callable

		When you define a callable in a such manner, they are not modified in any way and are called as is. An only difference is that you can define dependency list in their parameter lists, which will be resolved via [yiisoft/injector](https://github.com/yiisoft/injector) and a DI Container.


		## Type 2: Callable definition extensions (via container)

		Under the hood, this extension behaves exactly like the Type 1 ones. But there is a major difference too:


		Let's see the built-in defaults.

		### [SendAgainMiddleware](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php)

	throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist', $name), 0, $exception);
	throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist.', $name), 0, $exception);

Uh oh!

Documentation #250

Are you sure you want to change the base?

Documentation #250

Uh oh!

Conversation

viktorprogger commented Dec 13, 2025

Uh oh!

codecov bot commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Dec 13, 2025 •

edited

Loading