Add comprehensive documentation for callable definitions and update related guides

Author: viktorprogger

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.  
+It is used across the package to convert configuration definitions into real callables.
+
+## 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.  
+As you can see in the [PHP documentation](https://www.php.net/manual/en/language.types.callable.php), there are several ways to define a native callable:
+
+- **Closure (lambda function)**. It may be static. Example:
+  ```php
+  $callable = static function(Update $update) {
+    // do stuff
+  }
+  ```
+- **First class callable**. It's a Closure too, BTW ;) Example:
+  ```php
+  $callable = trim(...);
+  $callable2 = $this->foo(...);
+  ```
+- **A class static function**. When a class has a static function, an array syntax may be used:
+  ```php
+  $callable = [Foo::class, 'bar']; // this will be called the same way as Foo::bar();
+  ```
+- **An object method**. The same as above, but with an object and a non-static method:
+  ```php
+  $foo = new Foo();
+  $callable = [$foo, 'bar']; // this will be called the same way as $foo->bar();
+  ```
+- **A class static function as a string**. I don't recommend you to use this ability, as it's non-obvious and
+  hard to refactor, but it still exists:
+  ```php
+  $callable = 'Foo::bar'; // this will be called the same way as Foo::bar();
+  ```
+- **A name of a named function**:
+  ```php
+  function foo() {
+    // do stuff
+  }
+  $callable = 'foo';
+  $callable2 = 'array_map';
+  ```
+- **Callable objects**. An object with [the `__invoke` method](https://www.php.net/manual/en/language.oop5.magic.php#object.invoke) implemented:
+  ```php
+  class Foo 
+  {
+    public function __invoke()
+    {
+      // do stuff
+    }
+  }
+  
+  $callable = new Foo();
+  ```
+
+## 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:
+all the objects are instantiated automatically with a PSR-11 DI Container with all their dependencies
+and in a lazy way (only when they are really needed).  
+Ways to define an extended callable:
+
+- An object method through a class name or alias:
+  ```php
+  final readonly class Foo 
+  {
+    public function __construct(private MyHeavyDependency $dependency) {}
+  
+    public function bar()
+    {
+      // do stuff
+    }
+  }
+  
+  $callable = [Foo::class, 'bar'];
+  ```
+  Here is a simplified example of how it works:
+  ```php
+  if ($container->has($callable[0])) {
+    $callable[0] = $container->get($callable[0])
+  }
+  
+  $callable();
+  ```
+- Class name of an object with [the `__invoke` method](https://www.php.net/manual/en/language.oop5.magic.php#object.invoke) implemented:
+  ```php
+  $callable = Foo::class;
+  ```
+  It works the same way as above: an object will be retrieved from a DI container and called as a function.
+
+_Note: you can use an alias registered in your DI Container instead of a class name._ This will also work if you have a "class alias" definition in container:
+```php
+$callable = 'class alias'; // for a "callable object" 
+$callable2 = ['class alias', 'foo']; // to call "foo" method of an object found by "class alias" in DI Container
+```
+
+## Invalid definitions
+
+The factory throws `Yiisoft\Queue\Middleware\InvalidCallableConfigurationException` when it cannot create a callable (for example: `null`, unsupported array format, missing method, container entry is not callable).

docs/guide/en/configuration-manual.md

@@ -16,6 +16,7 @@ To use the queue, you need to create instances of the following classes:
 use Yiisoft\Queue\Adapter\SynchronousAdapter;
 use Yiisoft\Queue\Queue;
 use Yiisoft\Queue\Worker\Worker;
+use Yiisoft\Queue\Middleware\CallableFactory;
 use Yiisoft\Queue\Middleware\Consume\ConsumeMiddlewareDispatcher;
 use Yiisoft\Queue\Middleware\Consume\MiddlewareFactoryConsume;
 use Yiisoft\Queue\Middleware\FailureHandling\FailureMiddlewareDispatcher;
@@ -33,13 +34,15 @@ $handlers = [
     FileDownloader::class => [FileDownloader::class, 'handle'],
 ];
 
+$callableFactory = new CallableFactory($container);
+
 // Create middleware dispatchers
 $consumeMiddlewareDispatcher = new ConsumeMiddlewareDispatcher(
-    new MiddlewareFactoryConsume($container),
+    new MiddlewareFactoryConsume($container, $callableFactory),
 );
 
 $failureMiddlewareDispatcher = new FailureMiddlewareDispatcher(
-    new MiddlewareFactoryFailure($container),
+    new MiddlewareFactoryFailure($container, $callableFactory),
     [],
 );
 
@@ -55,6 +58,7 @@ $worker = new Worker(
     $container,
     $consumeMiddlewareDispatcher,
     $failureMiddlewareDispatcher,
+    $callableFactory,
 );
 
 // Create queue with adapter

docs/guide/en/error-handling.md

@@ -4,9 +4,7 @@ Often when some message handling is failing, we want to retry its execution a co
 
 ## Configuration
 
-Here below is configuration via [yiisoft/config](https://github.com/yiisoft/config). If you don't use it, you should add a middleware definition list (in the `middlewares-fail` key here) to the `FailureMiddlewareDispatcher` by your own.
-
-Configuration should be passed to the `yiisoft/queue.fail-strategy-pipelines` key of the `params` config to work with the [yiisoft/config](https://github.com/yiisoft/config). You can define different failure handling pipelines for each queue channel. Let's see and describe an example:
+Here below is configuration via [yiisoft/config](https://github.com/yiisoft/config). If you don't use it, you should add a middleware definition list (in the `middlewares-fail` key here) to the `FailureMiddlewareDispatcher` by your own. You can define different failure handling pipelines for each queue channel. The example below defines two different failure handling pipelines:
 
 ```php
 'yiisoft/queue' => [
@@ -39,11 +37,15 @@ Configuration should be passed to the `yiisoft/queue.fail-strategy-pipelines` ke
 ]
 ```
 
-Keys here except `FailureMiddlewareDispatcher::DEFAULT_PIPELINE` are queue channel names, and values are lists of `FailureMiddlewareInterface` definitions. `FailureMiddlewareDispatcher::DEFAULT_PIPELINE` defines a default pipeline to apply to channels without an explicitly defined failure strategy pipeline. Each middleware definition must be one of:
+Here is the meaning of the keys:
+- The `failed-messages` key couples the defined pipeline with the `failed-messages` queue channel. 
+- The `FailureMiddlewareDispatcher::DEFAULT_PIPELINE` key couples the defined pipeline with all queue channels without an explicitly defined failure strategy pipeline.
+
+Each middleware definition must be one of:
 - A ready-to-use `MiddlewareFailureInterface` object like `new FooMiddleware()`.
 - A valid definition for the [yiisoft/definitions](https://github.com/yiisoft/definitions). It must describe an object, implementing the `MiddlewareFailureInterface`.
-- A callable: `fn() => // do stuff`, `$object->foo(...)`, etc. It will be executed through the [yiisoft/injector](https://github.com/yiisoft/injector), so all the dependencies of your callable will be resolved. You can also define a "callable-looking" array, where an object will be instantiated with a DI container: `[FooMiddleware::class, 'handle']`.
-- A string for your DI container to resolve the middleware, e.g. `FooMiddleware::class`.
+- An [extended callable definition](callable-definitions-extended.md).
+- An id string for your DI container to resolve a middleware, e.g. `FooMiddleware::class`.
 
 In the example above failures will be handled this way (look the concrete middleware description below):
 
@@ -58,15 +60,15 @@ Failures of messages, which are initially sent to the `failed-messages` channel,
 
 Let's see the built-in defaults.
 
-### SendAgainMiddleware
+### [SendAgainMiddleware](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php)
 
 This strategy simply resends the given message to a queue. Let's see the constructor parameters through which it's configured:
 
 - `id` - A unique string. Allows to use this strategy more than once for the same message, just like in example above.
 - `maxAttempts` - Maximum attempts count for this strategy with the given $id before it will give up.
 - `queue` - The strategy will send the message to the given queue when it's not `null`. That means you can use this strategy to push a message not to the same queue channel it came from. When the `queue` parameter is set to `null`, a message will be sent to the same channel it came from.
 
-### ExponentialDelayMiddleware
+### [ExponentialDelayMiddleware](../../../src/Middleware/FailureHandling/Implementation/ExponentialDelayMiddleware.php)
 
 This strategy does the same thing as the `SendAgainMiddleware` with a single difference: it resends a message with an exponentially increasing delay. The delay **must** be implemented by the used `AdapterInterface` implementation.
 
@@ -82,9 +84,11 @@ It's configured via constructor parameters, too. Here they are:
 ## How to create a custom Failure Middleware?
 
 All you need is to implement the `MiddlewareFailureInterface` and add your implementation definition to the [configuration](#configuration).
-This interface has the only method `handle`. And the method has these parameters:
-- `ConsumeRequest $request` - a request for a message handling. It consists of a message and a queue the message came from.
-- `Throwable $exception` - an exception thrown on the `request` handling
+This interface has the only method `handle` with these parameters:
+- [`FailureHandlingRequest $request`](../../../src/Middleware/FailureHandling/FailureHandlingRequest.php) - a request for a message handling. It consists of
+    - a [message](../../../src/Message/MessageInterface.php)
+    - a `Throwable $exception` object thrown on the `request` handling
+    - a queue the message came from
 - `MessageFailureHandlerInterface $handler` - failure strategy pipeline continuation. Your Middleware should call `$pipeline->handle()` when it shouldn't interrupt failure pipeline execution.
 
-> Note: your strategy have to check by its own if it should be applied. Look into [`SendAgainMiddleware::suites()`](../../src/Middleware/Implementation/FailureMiddleware/Middleware/SendAgainMiddleware.php#L52) for an example.
+> Note: your strategy have to check by its own if it should be applied. Look into [`SendAgainMiddleware::suites()`](../../../src/Middleware/FailureHandling/Implementation/SendAgainMiddleware.php#L54) for an example.

docs/guide/en/message-handler.md

@@ -9,11 +9,11 @@ Handler definitions are configured in:
 
 ## Supported handler definition formats
 
-`Worker` supports a limited set of formats. Below are the exact formats that are converted to a callable.
-
 ### 1. HandlerInterface implementation (without mapping)
 
-If your handler is a dedicated class implementing `Yiisoft\Queue\Message\MessageHandlerInterface`, you can use the class name itself as the message handler name.
+If your handler is a dedicated class implementing `Yiisoft\Queue\Message\MessageHandlerInterface`, you can use the class name itself as the message handler name (FQCN) if your DI container can resolve the handler class.
+
+> By default the [yiisoft/di](https://github.com/yiisoft/di) container resolves all FQCNs into corresponding class objects.
 
 This is the default and most convenient option when the producer and the consumer are the same application.
 
@@ -57,9 +57,9 @@ Not needed
 - Producer and consumer are the same application.
 - You control message creation code and can safely use FQCN as the handler name.
 
-### 2. Closure
+### 2. Named handlers
 
-In this and all the cases below, you should use a proper handler name when pushing a `Message` instead of a handler class name in the example above:
+In this case you should use a proper handler name when pushing a `Message` instead of a handler class name as in the example above:
 
 ```php
 new \Yiisoft\Queue\Message\Message('send-email', ['data' => '...']);
@@ -73,105 +73,13 @@ Map handler name to a closure in `$params`:
 return [
     'yiisoft/queue' => [
         'handlers' => [
-            'send-email' => static fn (\Yiisoft\Queue\Message\MessageInterface $message, \App\Foo $foo) => $foo->bar($message->getData()),
-        ],
-    ],
-];
-```
-
-**How it works**:
-
-- A `Closure` is accepted as-is.
-- The worker executes it using `Injector`, so you may type-hint extra dependencies in the closure parameters.
-
-**Pros**:
-
-- Very simple for small tasks and quick prototypes.
-- Easy to inject extra services via `Injector`.
-
-**Cons**:
-
-- Less reusable and harder to unit-test than a dedicated class.
-- Easy to accidentally put non-trivial business logic into config.
-- Harder to maintain and refactor as the logic grows.
-
-**Use when**:
-
-- You're prototyping async workflows and going to refactor it later into a proper handler class.
-- You want a quick "glue" handler that delegates to services.
-
-### 3. Container ID string
-
-**Config**:
-
-```php
-return [
-    'yiisoft/queue' => [
-        'handlers' => [
-            'file-download' => FileDownloader::class,
-        ],
-    ],
-];
-```
-
-**How it works**:
-
-The handler object is retrieved from the DI container. In this case the handler class should either
-
-- have the `__invoke()` method, which receives a message parameter,
-- implement `Yiisoft\Queue\Message\MessageHandlerInterface` (then the `$handler->handle(...)` method is called).
-
-If the resolved service is neither callable nor a `MessageHandlerInterface`, the handler is treated as invalid.
-
-**Pros**:
-
-- Short and clean configuration.
-- Supports invokable handlers and `MessageHandlerInterface` handlers.
-
-**Cons**:
-
-—
-
-**Use when**:
-
-- You already registered handlers in DI (recommended for production).
-- You prefer invokable handlers (`__invoke`) or `MessageHandlerInterface`.
-
-### 4. Two-element array of strings: `[classOrServiceId, method]`
-
-**Config**:
-
-```php
-return [
-    'yiisoft/queue' => [
-        'handlers' => [
-            'file-download' => [FileDownloader::class, 'handle'],
-            'file-download2' => [$handler, 'handle'],
+            'send-email' => /** handler definition */,
         ],
     ],
 ];
 ```
 
-**How it works**:
-
-- If the class exists:
-  - If the method is static, it is called statically: `[$className, $methodName]`. Dependencies may be passed *to the provided method* in case they are resolvable from the DI container.
-  - If the first element is an object instance, it is called as `$firstElement->$methodName(...)` with dependency injection applied *to the $methodName*.
-  - If the method is not static, the class must be resolvable from the DI container, and the worker calls `$container->get($className)->$methodName(...)`. DI container will also resolve dependencies declared in the *class constructor*.
-
-**Pros**:
-
-- Explicit method name, good for “classic” `handle()` methods.
-- Supports static methods for pure, dependency-free handlers.
-
-**Cons**:
-
-- Harder to maintain and refactor than regular class definitions with either `__invoke` method or `MessageHandlerInterface` implementation.
-
-**Use when**:
-
-- You want to use static handlers (rare, but can be useful for pure transforms).
-- You want to group different handlers in a single class for organizational purposes.
+Handler definition should be either an [extended callable definition](./callable-definitions-extended.md) or a string for your DI container to resolve a `MessageHandlerInterface` instance.
 
 ## When mapping by short names is a better idea
 
@@ -199,7 +107,7 @@ This way external producers never need to know your internal PHP class names.
 
 ## Common pitfalls and unsupported formats
 
-- A string definition is **not** treated as a function name. It is treated only as a DI container ID.
+- 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/middleware-pipelines.md

@@ -57,10 +57,9 @@ graph LR
 You can use any of these formats:
 
 - A ready-to-use middleware object.
-- An array in the format of [yiisoft/definitions](https://github.com/yiisoft/definitions).
-- A `callable` (closure, invokable object, `[$object, 'method']`, etc.). It is executed through the
-  [yiisoft/injector](https://github.com/yiisoft/injector), so its dependencies are resolved automatically.
+- An array in the format of [yiisoft/definitions](https://github.com/yiisoft/definitions), which defines a middleware implementation.
 - A string for your DI container to resolve the middleware, e.g. `FooMiddleware::class`.
+- An [extended callable definition](callable-definitions-extended.md). A callable should either be a middleware itself or return a configured middleware object.
 
 The required interface depends on the pipeline: