Document Mautic 8 class-name dispatch for Stage, Dashboard, and SMS bundle events

docs/plugin_extensions/sms.rst

@@ -150,12 +150,24 @@ Three events fire sequentially during SMS sending to filter Contacts before disp
 
 .. vale off
 
+.. note::
+
+   Since Mautic 8, Mautic dispatches these three filtering events by the event object alone, so you subscribe by the event class. See :ref:`Mautic 8 class-name event dispatch <Mautic 8 class-name event dispatch>` for the general rule. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. Other SmsBundle events converted in Mautic 8 - such as ``SmsSendEvent`` and ``TokensBuildEvent`` - aren't covered here. The Campaign trigger, CRUD, and reply events still key on their ``SmsEvents`` constants.
+
+   To confirm Mautic registered your listener under the event's class name, run:
+
+   .. code-block:: bash
+
+      bin/console debug:event-dispatcher 'Mautic\SmsBundle\Event\DncEvent'
+
+   Your subscriber's class and method appear in the listing for ``Mautic\SmsBundle\Event\DncEvent``. If they're absent, the subscriber isn't registered for that event.
+
 For how to register a subscriber, see the :doc:`listeners and subscribers</plugins/event_listeners>` section.
 
 Do Not Contact filter
 =====================
 
-Use ``SmsEvents::DNC_FILTER_CONTACTS_ON_SEND`` to filter Contacts based on **Do Not Contact** status.
+Subscribe by ``DncEvent::class`` - formerly ``SmsEvents::DNC_FILTER_CONTACTS_ON_SEND`` - to filter Contacts based on **Do Not Contact** status.
 
 .. vale on
 
@@ -166,21 +178,21 @@ Use ``SmsEvents::DNC_FILTER_CONTACTS_ON_SEND`` to filter Contacts based on **Do
    declare(strict_types=1);
 
    use Mautic\SmsBundle\Event\DncEvent;
-   use Mautic\SmsBundle\SmsEvents;
    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
    final class SmsFilterSubscriber implements EventSubscriberInterface
    {
        public static function getSubscribedEvents(): array
        {
            return [
-               SmsEvents::DNC_FILTER_CONTACTS_ON_SEND => ['onDncFilter', 0],
+               DncEvent::class => ['onDncFilter', 0],
            ];
        }
 
        public function onDncFilter(DncEvent $event): void
        {
            foreach ($event->getContacts() as $id => $contact) {
+               // shouldExclude() stands in for your own exclusion logic.
                if ($this->shouldExclude($contact)) {
                    $event->removeContact($id);
                }
@@ -191,12 +203,20 @@ Use ``SmsEvents::DNC_FILTER_CONTACTS_ON_SEND`` to filter Contacts based on **Do
 Queue filter
 ============
 
-Use ``SmsEvents::QUEUE_FILTER_CONTACTS_ON_SEND`` to filter Contacts based on frequency rules or queueing logic. Subscribe to it the same way, with a listener that receives a ``QueueEvent``.
+.. vale off
+
+Subscribe by ``QueueEvent::class`` - formerly ``SmsEvents::QUEUE_FILTER_CONTACTS_ON_SEND`` - to filter Contacts based on frequency rules or queueing logic. Its listener receives a ``QueueEvent``. See the Mautic 8 note at the start of this section about class-name dispatch.
+
+.. vale on
 
 Generic filter
 ==============
 
-Use ``SmsEvents::FILTER_CONTACTS_ON_SEND`` for any remaining filtering logic, such as removing Contacts without phone numbers. Its listener receives a ``FilterEvent``.
+.. vale off
+
+Subscribe by ``FilterEvent::class`` - formerly ``SmsEvents::FILTER_CONTACTS_ON_SEND`` - for any remaining filtering logic, such as removing Contacts without phone numbers. Its listener receives a ``FilterEvent``. See the Mautic 8 note at the start of this section about class-name dispatch.
+
+.. vale on
 
 All three event classes share a common API, shown here for :xref:`FilterEvent source`:
 
@@ -252,10 +272,10 @@ The :xref:`SmsEvents source` class defines all SMS-related event constants:
    * - ``ON_CAMPAIGN_TRIGGER_ACTION``
      - Fires when a Campaign triggers an SMS action for a single Contact.
    * - ``DNC_FILTER_CONTACTS_ON_SEND``
-     - Fires to filter Contacts based on **Do Not Contact** status.
+     - Fires to filter Contacts based on **Do Not Contact** status. Since Mautic 8, Mautic dispatches this event by class - ``DncEvent``. The constant is no longer the subscription key.
    * - ``QUEUE_FILTER_CONTACTS_ON_SEND``
-     - Fires to filter Contacts based on frequency rules.
+     - Fires to filter Contacts based on frequency rules. Since Mautic 8, Mautic dispatches this event by class - ``QueueEvent``. The constant is no longer the subscription key.
    * - ``FILTER_CONTACTS_ON_SEND``
-     - Fires for generic Contact filtering before SMS dispatch.
+     - Fires for generic Contact filtering before SMS dispatch. Since Mautic 8, Mautic dispatches this event by class - ``FilterEvent``. The constant is no longer the subscription key.
 
 .. vale on

docs/plugins/event_listeners.rst

@@ -74,6 +74,48 @@ Available events
 
 There are many events available throughout Mautic. Depending on what you're trying to implement, look at the ``*Event.php`` for the core bundle, located in the root of the bundle. For example, the ``app\bundles\LeadBundle\LeadEvents.php`` file defines and describes events relating to Contacts. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names won't break the Plugin.
 
+.. vale off
+
+Since Mautic 8, some bundles dispatch an event by the event object alone rather than by a string constant, so you key ``getSubscribedEvents()`` on the event class. See :ref:`Mautic 8 class-name event dispatch <Mautic 8 class-name event dispatch>` for the general rule. The notes below cover the StageBundle and DashboardBundle events.
+
+.. note::
+
+   Since Mautic 8, Mautic dispatches ``Mautic\StageBundle\Event\StageBuilderEvent`` by the event object alone. Key ``getSubscribedEvents()`` on ``StageBuilderEvent::class``, not on ``StageEvents::STAGE_ON_BUILD`` or the string ``mautic.stage_on_build``. Those constants remain for backward compatibility but no longer dispatch this event. The ``StageEvent`` CRUD group, ``STAGE_ON_ACTION``, and ``ON_CAMPAIGN_BATCH_ACTION`` are unchanged.
+
+   .. code-block:: php
+
+      return [
+          StageBuilderEvent::class => ['onStageBuild', 0],
+          // ...
+      ];
+
+.. note::
+
+   Since Mautic 8, Mautic dispatches two DashboardBundle widget events by the event object alone. Key ``getSubscribedEvents()`` on the event class rather than on the former constant. The classes live in ``Mautic\DashboardBundle\Event``.
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 50 50
+
+      * - Former event constant
+        - Mautic 8 event class - subscription key
+      * - ``DASHBOARD_ON_MODULE_LIST_GENERATE``
+        - ``WidgetTypeListEvent``
+      * - ``DASHBOARD_ON_MODULE_FORM_GENERATE``
+        - ``WidgetFormEvent``
+
+   The former constants remain for backward compatibility but no longer dispatch these events. ``DASHBOARD_ON_MODULE_DETAIL_GENERATE`` and ``DASHBOARD_ON_MODULE_DETAIL_PRE_LOAD`` - both sharing ``WidgetDetailEvent`` - remain string-keyed and unchanged.
+
+   .. code-block:: php
+
+      return [
+          WidgetTypeListEvent::class => ['onWidgetListGenerate', 0],
+          WidgetFormEvent::class     => ['onWidgetFormGenerate', 0],
+          // ...
+      ];
+
+.. vale on
+
 Custom events
 *************