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

---
 components/event_dispatcher.rst | 39 ++++++++++-----------------------
 1 file changed, 12 insertions(+), 27 deletions(-)

diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst
index 9d33ec6869e..03e79e4a607 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
 .............................
 
@@ -257,7 +246,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::
@@ -268,17 +257,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
     {
-        public const NAME = 'order.placed';
-
-        public function __construct(
-            protected Order $order,
-        ) {
-        }
+        public function __construct(protected Order $order) {}
 
         public function getOrder(): Order
         {
@@ -314,10 +298,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:
@@ -336,7 +320,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;
 
@@ -354,7 +338,7 @@ Take the following example of a subscriber that subscribes to the
                     ['onKernelResponsePre', 10],
                     ['onKernelResponsePost', -10],
                 ],
-                OrderPlacedEvent::NAME => 'onStoreOrder',
+                OrderPlacedEvent::class => 'onPlacedOrder',
             ];
         }
 
@@ -368,8 +352,9 @@ Take the following example of a subscriber that subscribes to the
             // ...
         }
 
-        public function onStoreOrder(OrderPlacedEvent $event): void
+        public function onPlacedOrder(OrderPlacedEvent $event): void
         {
+            $order = $event->getOrder();
             // ...
         }
     }
@@ -413,14 +398,14 @@ inside a listener via the
 
     use Acme\Store\Event\OrderPlacedEvent;
 
-    public function onStoreOrder(OrderPlacedEvent $event): void
+    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