feature #28294 [Messenger] Remove the "obscure" message subscriber configuration (sroze)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[Messenger] Remove the "obscure" message subscriber configuration

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | yes
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | ø
| License       | MIT
| Doc PR        | ø

As described in #28275, all of the configuration can be done using yield and that we could remove the support for other ways (especially the obscure return `[['method', -10]]` syntax) as I believe this would clarify the configuration a lot.

Commits
-------

cf2ad861f5 Remove the "obscure" message subscriber configuration

Author: fabpot

CHANGELOG.md

@@ -4,6 +4,8 @@ CHANGELOG
 4.2.0
 -----
 
+ * [BC BREAK] `MessageSubscriberInterface::getHandledMessages()` return value has changed. The value of an array item
+   needs to be an associative array or the method name. 
  * `ValidationMiddleware::handle()` and `SendMessageMiddleware::handle()` now require an `Envelope` object
  * `EnvelopeItemInterface` doesn't extend `Serializable` anymore
  * [BC BREAK] The `ConsumeMessagesCommand` class now takes an instance of `Psr\Container\ContainerInterface` 

DependencyInjection/MessengerPass.php

@@ -111,30 +111,21 @@ private function registerHandlers(ContainerBuilder $container, array $busIds)
                     }
 
                     if (\is_array($method)) {
-                        if (isset($method[0]) && isset($method[1])) {
-                            $messagePriority = $method[1];
-                            $method = $method[0];
-                        } elseif (isset($method['method']) || isset($method['bus'])) {
-                            if (isset($method['bus'])) {
-                                if (!\in_array($method['bus'], $busIds)) {
-                                    $messageClassLocation = isset($tag['handles']) ? 'declared in your tag attribute "handles"' : $r->implementsInterface(MessageSubscriberInterface::class) ? sprintf('returned by method "%s::getHandledMessages()"', $r->getName()) : sprintf('used as argument type in method "%s::%s()"', $r->getName(), $method);
-
-                                    throw new RuntimeException(sprintf('Invalid configuration %s for message "%s": bus "%s" does not exist.', $messageClassLocation, $messageClass, $method['bus']));
-                                }
-
-                                $buses = array($method['bus']);
-                            }
+                        if (isset($method['bus'])) {
+                            if (!\in_array($method['bus'], $busIds)) {
+                                $messageClassLocation = isset($tag['handles']) ? 'declared in your tag attribute "handles"' : $r->implementsInterface(MessageSubscriberInterface::class) ? sprintf('returned by method "%s::getHandledMessages()"', $r->getName()) : sprintf('used as argument type in method "%s::%s()"', $r->getName(), $method);
 
-                            if (isset($method['priority'])) {
-                                $messagePriority = $method['priority'];
+                                throw new RuntimeException(sprintf('Invalid configuration %s for message "%s": bus "%s" does not exist.', $messageClassLocation, $messageClass, $method['bus']));
                             }
 
-                            $method = $method['method'] ?? '__invoke';
-                        } else {
-                            $messageClassLocation = isset($tag['handles']) ? 'declared in your tag attribute "handles"' : $r->implementsInterface(MessageSubscriberInterface::class) ? sprintf('returned by method "%s::getHandledMessages()"', $r->getName()) : sprintf('used as argument type in method "%s::%s()"', $r->getName(), $method);
+                            $buses = array($method['bus']);
+                        }
 
-                            throw new RuntimeException(sprintf('Invalid configuration %s for message "%s".', $messageClassLocation, $messageClass));
+                        if (isset($method['priority'])) {
+                            $messagePriority = $method['priority'];
                         }
+
+                        $method = $method['method'] ?? '__invoke';
                     }
 
                     if (!\class_exists($messageClass) && !\interface_exists($messageClass)) {

Handler/MessageSubscriberInterface.php

@@ -25,22 +25,25 @@ interface MessageSubscriberInterface extends MessageHandlerInterface
      *
      * It returns a list of messages like in the following example:
      *
-     *     return [MyMessage::class];
+     *     yield MyMessage::class;
      *
      * It can also change the priority per classes.
      *
-     *     return [
-     *         [FirstMessage::class, 0],
-     *         [SecondMessage::class, -10],
-     *     ];
+     *     yield FirstMessage::class => ['priority' => 0];
+     *     yield SecondMessage::class => ['priority => -10];
      *
-     * It can also specify a method and/or a priority per message:
+     * It can also specify a method, a priority and/or a bus per message:
      *
-     *     return [
-     *         FirstMessage::class => 'firstMessageMethod',
-     *         SecondMessage::class => ['secondMessageMethod', 20],
+     *     yield FirstMessage::class => ['method' => 'firstMessageMethod'];
+     *     yield SecondMessage::class => [
+     *         'method' => 'secondMessageMethod',
+     *         'priority' => 20,
+     *         'bus' => 'my_bus_name',
      *     ];
      *
+     * The benefit of using `yield` instead of returning an array is that you can `yield` multiple times the
+     * same key and therefore subscribe to the same message multiple times with different options.
+     *
      * The `__invoke` method of the handler will be called as usual with the message to handle.
      */
     public static function getHandledMessages(): iterable;

Tests/DependencyInjection/MessengerPassTest.php

@@ -723,9 +723,7 @@ class PrioritizedHandler implements MessageSubscriberInterface
 {
     public static function getHandledMessages(): iterable
     {
-        return array(
-            array(SecondMessage::class, 10),
-        );
+        yield SecondMessage::class => array('priority' => 10);
     }
 
     public function __invoke()
@@ -737,10 +735,8 @@ class HandlerMappingMethods implements MessageSubscriberInterface
 {
     public static function getHandledMessages(): iterable
     {
-        return array(
-            DummyMessage::class => 'dummyMethod',
-            SecondMessage::class => array('secondMessage', 20),
-        );
+        yield DummyMessage::class => 'dummyMethod';
+        yield SecondMessage::class => array('method' => 'secondMessage', 'priority' => 20);
     }
 
     public function dummyMethod()