Merge branch '6.0' into 6.1

wouterj · wouterj · commit 7866a09a9d4e · 2022-01-19T17:28:10.000+01:00
* 6.0: Removed 5.4 versionadded [#15990] Minor changes [Messenger] Autoconfigurable attributes
diff --git a/messenger.rst b/messenger.rst
@@ -51,24 +51,31 @@ serialized::
 .. _messenger-handler:
 
 A message handler is a PHP callable, the recommended way to create it is to
-create a class that implements :class:`Symfony\\Component\\Messenger\\Handler\\MessageHandlerInterface`
-and has an ``__invoke()`` method that's type-hinted with the message class (or a
-message interface)::
+create a class that has the :class:`Symfony\\Component\\Messenger\\Attribute\\AsMessageHandler`
+attribute and has an ``__invoke()`` method that's type-hinted with the
+message class (or a message interface)::
 
     // src/MessageHandler/SmsNotificationHandler.php
     namespace App\MessageHandler;
 
     use App\Message\SmsNotification;
-    use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
+    use Symfony\Component\Messenger\Attribute\AsMessageHandler;
 
-    class SmsNotificationHandler implements MessageHandlerInterface
+    #[AsMessageHandler]
+    class SmsNotificationHandler
     {
         public function __invoke(SmsNotification $message)
         {
             // ... do some work - like sending an SMS message!
         }
     }
 
+.. note::
+
+    You can also create a class without the attribute (e.g. if you're
+    using PHP 7.4), by implementing :class:`Symfony\\Component\\Messenger\\Handler\\MessageHandlerInterface`
+    instead.
+
 Thanks to :ref:`autoconfiguration <services-autoconfigure>` and the ``SmsNotification``
 type-hint, Symfony knows that this handler should be called when an ``SmsNotification``
 message is dispatched. Most of the time, this is all you need to do. But you can
@@ -349,9 +356,10 @@ Then, in your handler, you can query for a fresh object::
 
     use App\Message\NewUserWelcomeEmail;
     use App\Repository\UserRepository;
-    use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
+    use Symfony\Component\Messenger\Attribute\AsMessageHandler;
 
-    class NewUserWelcomeEmailHandler implements MessageHandlerInterface
+    #[AsMessageHandler]
+    class NewUserWelcomeEmailHandler
     {
         private $userRepository;
 
@@ -1673,6 +1681,35 @@ on a case-by-case basis via the :class:`Symfony\\Component\\Messenger\\Stamp\\Se
 Customizing Handlers
 --------------------
 
+Configuring Handlers Using Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can configure your handler by passing options to the attribute::
+
+    // src/MessageHandler/SmsNotificationHandler.php
+    namespace App\MessageHandler;
+
+    use App\Message\OtherSmsNotification;
+    use App\Message\SmsNotification;
+    use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+    #[AsMessageHandler(fromTransport: 'async', priority: 10)]
+    class SmsNotificationHandler
+    {
+        public function __invoke(SmsNotification $message)
+        {
+            // ...
+        }
+    }
+
+Possible options to configure with the attribute are:
+
+* ``bus``
+* ``fromTransport``
+* ``handles``
+* ``method``
+* ``priority``
+
 .. _messenger-handler-config:
 
 Manually Configuring Handlers
