From 4e04a454e5326a984a4fe5f8ae83f8300d523fcb Mon Sep 17 00:00:00 2001
From: Antoine M <amakdessi@me.com>
Date: Wed, 3 Jan 2024 14:12:22 +0100
Subject: [PATCH] [EventDispatcher] docs: document simpler event dispatching

---
 components/event_dispatcher.rst | 43 ++++++++++-----------------------
 1 file changed, 13 insertions(+), 30 deletions(-)

diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst
index f6f30419f68..6ad6e1dd80b 100644
--- a/components/event_dispatcher.rst
+++ b/components/event_dispatcher.rst
@@ -69,17 +69,6 @@ An :class:`Symfony\\Contracts\\EventDispatcher\\Event` instance is also
 created and passed to all of the listeners. As you'll see later, the ``Event``
 object itself often contains data about the event being dispatched.
 
-Naming Conventions
-..................
-
-The unique event name can be any string, but optionally follows a few
-naming conventions:
-
-* Use only lowercase letters, numbers, dots (``.``) and underscores (``_``);
-* Prefix names with a namespace followed by a dot (e.g. ``order.*``, ``user.*``);
-* End names with a verb that indicates what action has been taken (e.g.
-  ``order.placed``).
-
 Event Names and Event Objects
 .............................
 
@@ -259,7 +248,7 @@ system flexible and decoupled.
 Creating an Event Class
 .......................
 
-Suppose you want to create a new event - ``order.placed`` - that is dispatched
+Suppose you want to create a new event that is dispatched
 each time a customer orders a product with your application. When dispatching
 this event, you'll pass a custom event instance that has access to the placed
 order. Start by creating this custom event class and documenting it::
@@ -270,19 +259,12 @@ order. Start by creating this custom event class and documenting it::
     use Symfony\Contracts\EventDispatcher\Event;
 
     /**
-     * The order.placed event is dispatched each time an order is created
-     * in the system.
+     * This event is dispatched each time an order
+     * is placed in the system.
      */
-    class OrderPlacedEvent extends Event
+    final class OrderPlacedEvent extends Event
     {
-        public const NAME = 'order.placed';
-
-        protected $order;
-
-        public function __construct(Order $order)
-        {
-            $this->order = $order;
-        }
+        public function __construct(private Order $order) {}
 
         public function getOrder(): Order
         {
@@ -318,10 +300,10 @@ of the event to dispatch::
 
     // creates the OrderPlacedEvent and dispatches it
     $event = new OrderPlacedEvent($order);
-    $dispatcher->dispatch($event, OrderPlacedEvent::NAME);
+    $dispatcher->dispatch($event);
 
 Notice that the special ``OrderPlacedEvent`` object is created and passed to
-the ``dispatch()`` method. Now, any listener to the ``order.placed``
+the ``dispatch()`` method. Now, any listener to the ``OrderPlacedEvent::class``
 event will receive the ``OrderPlacedEvent``.
 
 .. _event_dispatcher-using-event-subscribers:
@@ -340,7 +322,7 @@ events it should subscribe to. It implements the
 interface, which requires a single static method called
 :method:`Symfony\\Component\\EventDispatcher\\EventSubscriberInterface::getSubscribedEvents`.
 Take the following example of a subscriber that subscribes to the
-``kernel.response`` and ``order.placed`` events::
+``kernel.response`` and ``OrderPlacedEvent::class`` events::
 
     namespace Acme\Store\Event;
 
@@ -358,7 +340,7 @@ Take the following example of a subscriber that subscribes to the
                     ['onKernelResponsePre', 10],
                     ['onKernelResponsePost', -10],
                 ],
-                OrderPlacedEvent::NAME => 'onStoreOrder',
+                OrderPlacedEvent::class => 'onPlacedOrder',
             ];
         }
 
@@ -372,8 +354,9 @@ Take the following example of a subscriber that subscribes to the
             // ...
         }
 
-        public function onStoreOrder(OrderPlacedEvent $event)
+        public function onPlacedOrder(OrderPlacedEvent $event): void
         {
+            $order = $event->getOrder();
             // ...
         }
     }
@@ -417,14 +400,14 @@ inside a listener via the
 
     use Acme\Store\Event\OrderPlacedEvent;
 
-    public function onStoreOrder(OrderPlacedEvent $event)
+    public function onPlacedOrder(OrderPlacedEvent $event): void
     {
         // ...
 
         $event->stopPropagation();
     }
 
-Now, any listeners to ``order.placed`` that have not yet been called will
+Now, any listeners to ``OrderPlacedEvent::class`` that have not yet been called will
 *not* be called.
 
 It is possible to detect if an event was stopped by using the