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.

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

README.md

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

README.md

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:

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

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?

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

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

viktorprogger added 3 commits January 18, 2026 18:37

Rewrite channels doc

dd30d79

Improve channel docs and fix PR comments

a86b307

Fix docs due to PR comments

19c4c44

	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:


		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!

samdark Dec 14, 2025

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

samdark Jan 7, 2026

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