Document Mautic 8 class-name dispatch for Stage, Dashboard, and SMS bundle events by promptless-for-oss · Pull Request #649 · mautic/developer-documentation-new

promptless-for-oss · 2026-09-01T09:47:01Z

Since Mautic 8, the StageBundle stage-builder event, the two DashboardBundle widget events, and the SmsBundle Contact-filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so the event name is now the event class rather than a string constant. The old StageEvents, DashboardEvents, and SmsEvents constants remain for backward compatibility but no longer dispatch these events — a plugin subscriber still keyed on an old constant fails silently, so the existing string-keyed subscriber guidance became inaccurate.

This updates the two affected developer pages so plugin authors key getSubscribedEvents() on the event class:

docs/plugins/event_listeners.rst — adds StageBundle and DashboardBundle notes (with a Dashboard constant-to-class mapping table) in the "Available events" section, reconciles the page's "always use the event constants" advice for converted events, and adds a generic bin/console debug:event-dispatcher verification step.
docs/plugin_extensions/sms.rst — re-keys the worked SmsFilterSubscriber example to DncEvent::class, recasts the DNC/Queue/Generic filter guidance to name the event class as the subscription key, adds a Mautic 8 silent-failure note (with a multi-version caveat and verification command), and annotates the SMS event-constants table.

Scope is limited to events already documented with string-keyed subscriber examples that the conversion made inaccurate; NotificationBundle's converted event and the other converted SMS events are undocumented and were left out.

Trigger Events

GitHub PR mautic/mautic#17216: Dispatch Notification, Dashboard, Stage and Sms bundle events by class name

Review feedback addressed (@adiati98, review 5086643454)

Applied all 13 actionable comments across the two pages. Three requested transforms:

Parentheses → spaced-hyphen asides (- … -, matching the repo convention in docs/design/labelling.rst): intro paragraph and the "Mautic 8 event class - subscription key" table header and WidgetDetailEvent aside in event_listeners.rst; the class-name-dispatch note, the three filter-section "formerly SmsEvents::…" asides, and the three SMS event-constants table rows in sms.rst.
Passive → active voice: the StageBuilderEvent, DashboardBundle, and SMS filtering-event dispatch sentences ("Mautic dispatches …"), the "Mautic throws no exception, logs nothing" clause, the debug:event-dispatcher verification sentences, and the three SMS table rows.
Semicolon → period + new sentence: the "…DashboardBundle events. Other bundles…" sentence, the event_listeners.rst verification note, and the three SMS table rows.

Disposition: all 13 items applied. The sms.rst verification sentence was applied verbatim per the supplied suggestion block (semicolon → period only; passive retained as suggested). For consistency, three em-dash asides in the same paragraphs were also normalised to the repo's spaced-hyphen form. Vale passes clean on both files.

… SMS bundles Since Mautic 8 (mautic/mautic#17216), StageBuilderEvent, the Dashboard widget-list/form events, and the SMS Contact-filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch). The old SmsEvents/StageEvents/DashboardEvents string constants remain for backward compatibility but no longer dispatch these events, so a subscriber still keyed on an old constant fails silently. Update the plugin event-listener and SMS extension guides to key getSubscribedEvents() on the event class, add a debug:event-dispatcher verification step, and annotate the SMS event-constants table.

promptless-for-oss · 2026-09-01T09:47:17Z

+
+.. note::
+
+   Since Mautic 8, ``Mautic\StageBundle\Event\StageBuilderEvent`` is dispatched 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, so a subscriber still keyed on the old constant never fires — no exception is thrown and nothing is logged. The ``StageEvent`` CRUD group, ``STAGE_ON_ACTION``, and ``ON_CAMPAIGN_BATCH_ACTION`` are unchanged.


StageModel::getStageActions() dispatches StageBuilderEvent via $this->dispatcher->dispatch($event) with no event-name argument, so Symfony uses StageBuilderEvent::class as the event name (class-name dispatch). StageEvents::STAGE_ON_BUILD constant (StageEvents.php L45) still exists but is no longer passed to dispatch().

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/StageBundle/Model/StageModel.php#L142

promptless-for-oss · 2026-09-01T09:47:18Z

+
+.. note::
+
+   Since Mautic 8, ``Mautic\StageBundle\Event\StageBuilderEvent`` is dispatched 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, so a subscriber still keyed on the old constant never fires — no exception is thrown and nothing is logged. The ``StageEvent`` CRUD group, ``STAGE_ON_ACTION``, and ``ON_CAMPAIGN_BATCH_ACTION`` are unchanged.


UPGRADE-8.0.md confirms StageEvents::STAGE_ON_BUILD constant is kept for backward compatibility but no longer used internally; STAGE_PRE_SAVE/POST_SAVE/PRE_DELETE/POST_DELETE (StageEvent) and ON_CAMPAIGN_BATCH_ACTION (PendingEvent) remain unchanged, matching the doc's claim.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/UPGRADE-8.0.md#L380

promptless-for-oss · 2026-09-01T09:47:19Z

+
+   Since Mautic 8, two DashboardBundle widget events are dispatched 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::


DashboardSubscriber::getSubscribedEvents() keys the widget list/form events on WidgetTypeListEvent::class and WidgetFormEvent::class (L37-38), replacing the former DashboardEvents::DASHBOARD_ON_MODULE_LIST_GENERATE/FORM_GENERATE string keys, while DASHBOARD_ON_MODULE_DETAIL_PRE_LOAD/GENERATE (L39-40, sharing WidgetDetailEvent) remain string-keyed, matching the doc's mapping table exactly.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/DashboardBundle/EventListener/DashboardSubscriber.php#L37

promptless-for-oss · 2026-09-01T09:47:20Z

+
+   Since Mautic 8, two DashboardBundle widget events are dispatched 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::


DashboardEvents.php still defines DASHBOARD_ON_MODULE_LIST_GENERATE (L18, string mautic.dashboard_on_widget_list_generate) and DASHBOARD_ON_MODULE_FORM_GENERATE (L26) for BC, confirming the doc's "former constant" column and the constant strings referenced.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/DashboardBundle/DashboardEvents.php#L18

promptless-for-oss · 2026-09-01T09:47:21Z


+.. note::
+
+   Since Mautic 8, these three filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so you subscribe by the event class. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. A subscriber still keyed on an old constant fails silently: no exception is thrown, nothing is logged, and the listener never runs. Within the SmsBundle, this section covers the three Contact-filtering 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.


SmsModel::sendSms() dispatches DncEvent (L233), QueueEvent (L250), and FilterEvent (L267) each via dispatch($event) with no event-name argument, i.e. class-name dispatch; the SmsEvents string constants (DNC_FILTER_CONTACTS_ON_SEND, QUEUE_FILTER_CONTACTS_ON_SEND, FILTER_CONTACTS_ON_SEND) are no longer passed.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/SmsBundle/Model/SmsModel.php#L233

promptless-for-oss · 2026-09-01T09:47:22Z

       {
           return [
-               SmsEvents::DNC_FILTER_CONTACTS_ON_SEND => ['onDncFilter', 0],
+               DncEvent::class => ['onDncFilter', 0],


SendSmsSubscriber::getSubscribedEvents() keys DncEvent::class, QueueEvent::class, and FilterEvent::class (L30-32) rather than the former SmsEvents string constants, matching the doc's code sample and the "Subscribe by DncEvent::class (formerly SmsEvents::DNC_FILTER_CONTACTS_ON_SEND)" claims for all three filter sections.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/SmsBundle/EventListener/SendSmsSubscriber.php#L30

promptless-for-oss · 2026-09-01T09:47:23Z

+
+   .. code-block:: bash
+
+      bin/console debug:event-dispatcher 'Mautic\SmsBundle\Event\DncEvent'


Symfony docs confirm: (1) dispatch($event) without an eventName uses the event's FQCN as the event name (class-name dispatch); (2) bin/console debug:event-dispatcher is a real console command that accepts an event name/FQCN and lists its registered listeners, so bin/console debug:event-dispatcher 'Mautic\SmsBundle\Event\DncEvent' is a valid, accurate verification command.

Source: https://symfony.com/doc/current/components/event_dispatcher.html

promptless-for-oss · 2026-09-01T09:47:24Z


+.. note::
+
+   Since Mautic 8, these three filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so you subscribe by the event class. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. A subscriber still keyed on an old constant fails silently: no exception is thrown, nothing is logged, and the listener never runs. Within the SmsBundle, this section covers the three Contact-filtering 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.


SmsEvents::ON_CAMPAIGN_TRIGGER_ACTION (L61) and ON_CAMPAIGN_TRIGGER_BATCH_ACTION (L67) are untouched by PR mautic/mautic#17216 (not in the changed-files list) and remain string constants, still used as the getSubscribedEvents key and batchEventName value in CampaignSendSubscriber.php (L28, L40 at head commit), supporting the doc's "The Campaign trigger ... events still key on their SmsEvents constants" claim (corrected pass: re-pinned from stale L228 to the actual claim location, L155).

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/SmsBundle/SmsEvents.php#L67

promptless-for-oss · 2026-09-01T09:47:25Z


+.. note::
+
+   Since Mautic 8, these three filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so you subscribe by the event class. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. A subscriber still keyed on an old constant fails silently: no exception is thrown, nothing is logged, and the listener never runs. Within the SmsBundle, this section covers the three Contact-filtering 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.


SmsModel::dispatchEvent() still resolves $name to the SmsEvents::SMS_PRE_SAVE/SMS_POST_SAVE/SMS_PRE_DELETE/SMS_POST_DELETE string constants (L421,424,427,430) and passes $name as the dispatch event-name argument (L442, dispatch($event, $name)) — untouched by PR #17216 (SmsModel.php's diff only touches the filter/send dispatches at L233/250/267/297). Confirms the doc's claim that "the CRUD ... events still key on their SmsEvents constants" is accurate.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/SmsBundle/Model/SmsModel.php#L421-L442

promptless-for-oss · 2026-09-01T09:47:26Z


+.. note::
+
+   Since Mautic 8, these three filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so you subscribe by the event class. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. A subscriber still keyed on an old constant fails silently: no exception is thrown, nothing is logged, and the listener never runs. Within the SmsBundle, this section covers the three Contact-filtering 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.


ReplySubscriber::getSubscribedEvents() still keys on the SmsEvents::ON_REPLY string constant (L31); this file is untouched by PR #17216 (not in the changed-files list), and SmsEvents::ON_CAMPAIGN_REPLY is likewise unconverted. Confirms the doc's claim that "the ... reply events still key on their SmsEvents constants" is accurate.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/SmsBundle/EventListener/ReplySubscriber.php#L31

promptless-for-oss · 2026-09-01T09:47:27Z


+.. vale off
+
+That advice holds for every event dispatched by a string constant. Since Mautic 8, some bundles instead dispatch an event by the event object alone (Symfony 4.3+ class-name dispatch), so the event name is the event class rather than a string constant. For a converted event, the event class — not a string constant — is the stable dispatch identifier, and you key ``getSubscribedEvents()`` on the class. The notes below cover the StageBundle and DashboardBundle events; other bundles received similar conversions in this release.


CampaignSubscriber::buildNotificationToSend() now calls $this->dispatcher->dispatch(new NotificationSendEvent(...)) with no event-name argument (L234-235), i.e. class-name dispatch, replacing the former NotificationEvents::NOTIFICATION_ON_SEND string-keyed dispatch — part of the same PR #17216 that converted StageBundle/DashboardBundle events. Supports the corrected bridging sentence's claim that "other bundles received similar conversions in this release" without overclaiming the notes below are exhaustive.

Source: https://github.com/mautic/mautic/blob/d854bbb37faac0d324b55182545d824a942219cf/app/bundles/NotificationBundle/EventListener/CampaignSubscriber.php#L234-L235

adiati98

@promptless-for-oss please address the suggestions.

promptless-for-oss · 2026-09-02T07:17:24Z

Thanks @adiati98 — on it. I'll work through all the review comments (hyphens instead of parentheses, active voice, and periods in place of semicolons), run Vale, and push the updates to this PR shortly.

@adiati98

Apply @adiati98's review on PR mautic#649: convert parenthetical asides to the repo's spaced-hyphen form, rewrite flagged passive constructions to active voice, and split semicolons into separate sentences across the StageBundle/DashboardBundle notes and the SMS Contact-filtering events.

promptless-for-oss · 2026-09-02T07:33:53Z

Done @adiati98 — worked through all of your review comments across docs/plugins/event_listeners.rst and docs/plugin_extensions/sms.rst: parenthetical asides converted to the spaced-hyphen form, passive voice made active, and semicolons replaced with periods (your suggested sentence applied verbatim). I also normalized a few em-dash asides in the same paragraphs to the hyphen convention for consistency. Vale passes on both files. Pushed to this PR branch — ready for another look.

promptless-for-oss commented Sep 1, 2026

View reviewed changes

promptless-for-oss mentioned this pull request Sep 1, 2026

[symfony] Dispatch Notification, Dashboard, Stage and Sms bundle events by class name (Symfony 4.3 style) mautic/mautic#17216

Merged

adiati98 added this to the 8.0 milestone Sep 2, 2026

adiati98 requested changes Sep 2, 2026

View reviewed changes

Merge branch '7.2' into promptless/pr-17216-events-by-class

07c5b0c

adiati98 added the needs-rebase label Sep 2, 2026

promptless-for-oss marked this pull request as ready for review September 2, 2026 18:02

promptless-for-oss requested review from a team, adiati98 and favour-chibueze September 2, 2026 18:02


		.. note::

		Since Mautic 8, ``Mautic\StageBundle\Event\StageBuilderEvent`` is dispatched 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, so a subscriber still keyed on the old constant never fires — no exception is thrown and nothing is logged. The ``StageEvent`` CRUD group, ``STAGE_ON_ACTION``, and ``ON_CAMPAIGN_BATCH_ACTION`` are unchanged.


		Since Mautic 8, two DashboardBundle widget events are dispatched 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::


		.. note::

		Since Mautic 8, these three filtering events are dispatched by the event object alone (Symfony 4.3+ class-name dispatch), so you subscribe by the event class. The ``SmsEvents`` constants remain for backward compatibility but no longer dispatch these three events. A subscriber still keyed on an old constant fails silently: no exception is thrown, nothing is logged, and the listener never runs. Within the SmsBundle, this section covers the three Contact-filtering 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.


		.. code-block:: bash

		bin/console debug:event-dispatcher 'Mautic\SmsBundle\Event\DncEvent'


		.. vale off

		That advice holds for every event dispatched by a string constant. Since Mautic 8, some bundles instead dispatch an event by the event object alone (Symfony 4.3+ class-name dispatch), so the event name is the event class rather than a string constant. For a converted event, the event class — not a string constant — is the stable dispatch identifier, and you key ``getSubscribedEvents()`` on the class. The notes below cover the StageBundle and DashboardBundle events; other bundles received similar conversions in this release.

Uh oh!

Conversation

promptless-for-oss commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review feedback addressed (@adiati98, review 5086643454)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Sep 2, 2026

Uh oh!

promptless-for-oss commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

promptless-for-oss commented Sep 1, 2026 •

edited

Loading