Document Mautic 8.0 class-name dispatch for Email bundle events - #660
Document Mautic 8.0 class-name dispatch for Email bundle events#660promptless-for-oss wants to merge 4 commits into
Conversation
Update the Email plugin-extension examples to key getSubscribedEvents() on event class names (EmailOnBuildEvent, EmailSendEvent, EmailDisplayEvent, EmailOnTogglePublishEvent) instead of the removed EmailEvents string constants, rename EmailBuilderEvent to EmailOnBuildEvent, and add BC-break notes explaining the Mautic 8.0 migration. Source: mautic/mautic#17225
| ===================================== | ||
|
|
||
| Registering tokens leverages the ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_BUILD`` event. The event is dispatched before displaying the email builder form, to allow adding of tokens. | ||
| Registering tokens uses the ``Mautic\EmailBundle\Event\EmailOnBuildEvent`` event. Since Mautic 8.0, Mautic dispatches this event by class name, so subscribers key on ``EmailOnBuildEvent::class``. Mautic dispatches it before displaying the Email builder form, so subscribers can add tokens before the form displays. |
There was a problem hiding this comment.
Verified: EmailBuilderEvent renamed to EmailOnBuildEvent (git rename in PR diff); EMAIL_ON_BUILD is dispatched by class (EmailOnBuildEvent::class) as of Mautic 8.0, matching EmailEvents.php constant removal and BuilderSubscriber.php key changes.
Source: mautic/mautic#17225
| Registering tokens uses the ``Mautic\EmailBundle\Event\EmailOnBuildEvent`` event. Since Mautic 8.0, Mautic dispatches this event by class name, so subscribers key on ``EmailOnBuildEvent::class``. Mautic dispatches it before displaying the Email builder form, so subscribers can add tokens before the form displays. | ||
|
|
||
| An event listener receives the ``Mautic\EmailBundle\Event\EmailBuilderEvent``. | ||
| An event listener receives the ``Mautic\EmailBundle\Event\EmailOnBuildEvent``. |
There was a problem hiding this comment.
Verified: listener receives Mautic\EmailBundle\Event\EmailOnBuildEvent (renamed from EmailBuilderEvent); addToken() is available via parent Mautic\CoreBundle\Event\BuilderEvent, confirmed in app/bundles/CoreBundle/Event/BuilderEvent.php on 8.x.
Source: mautic/mautic#17225
| ======================= | ||
|
|
||
| To render custom tokens, use the ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_SEND`` event when Mautic sends the Email, or the ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_DISPLAY`` event when the Email displays in a browser such as after the Contact clicks the ``{webview_url}`` link. | ||
| To render custom tokens, key on the ``Mautic\EmailBundle\Event\EmailSendEvent`` event (``EmailSendEvent::class``) when Mautic sends the Email, or the ``Mautic\EmailBundle\Event\EmailDisplayEvent`` event (``EmailDisplayEvent::class``) when the Email displays in a browser, for example, when the Contact clicks the ``{webview_url}`` link. |
There was a problem hiding this comment.
Verified: EMAIL_ON_SEND now dispatched via EmailSendEvent::class (constant kept as webhook identifier per UPGRADE-8.0.md); EMAIL_ON_DISPLAY now dispatched via new EmailDisplayEvent::class (constant removed, confirmed in EmailEvents.php diff and UPGRADE-8.0.md removed-constants table).
Source: mautic/mautic#17225
| To render custom tokens, key on the ``Mautic\EmailBundle\Event\EmailSendEvent`` event (``EmailSendEvent::class``) when Mautic sends the Email, or the ``Mautic\EmailBundle\Event\EmailDisplayEvent`` event (``EmailDisplayEvent::class``) when the Email displays in a browser, for example, when the Contact clicks the ``{webview_url}`` link. | ||
|
|
||
| An event listener receives in both cases the ``Mautic\EmailBundle\Event\EmailSendEvent``. You can replace a custom token using the events ``$event->addToken($token, $contentToReplaceToken)``. | ||
| The send path receives a ``Mautic\EmailBundle\Event\EmailSendEvent``. The display path receives a ``Mautic\EmailBundle\Event\EmailDisplayEvent``, a subclass of ``EmailSendEvent`` that exposes the same ``addToken()``, ``getContent()``, and ``setContent()`` API. These are now separate classes, keyed separately: a listener keyed only on ``EmailSendEvent::class`` doesn't receive ``EmailDisplayEvent``, so a handler serving both paths must register under both keys. Replace a custom token using the event's ``$event->addToken($token, $contentToReplaceToken)``. |
There was a problem hiding this comment.
Verified: EmailDisplayEvent is final class EmailDisplayEvent extends EmailSendEvent {} (new file), inheriting addToken()/getContent()/setContent() from EmailSendEvent. Confirmed Symfony class-name dispatch means a listener keyed only on EmailSendEvent::class will not receive EmailDisplayEvent instances (get_class() based event name matching), so dual registration is required, matching the pattern in AssetBundle/EmailBundle BuilderSubscriber.php and EmailSubscriber.php.
Source: mautic/mautic#17225
| EmailEvents::EMAIL_ON_BUILD => ['onEmailBuild', 0], | ||
| EmailEvents::EMAIL_ON_SEND => ['onEmailGenerate', 0], | ||
| EmailEvents::EMAIL_ON_DISPLAY => ['onEmailGenerate', 0], | ||
| EmailOnBuildEvent::class => ['onEmailBuild', 0], |
There was a problem hiding this comment.
Verified: getSubscribedEvents() code sample keys (EmailOnBuildEvent::class, EmailSendEvent::class, EmailDisplayEvent::class) match the real subscriber changes in app/bundles/EmailBundle/EventListener/BuilderSubscriber.php and DateTimeTokenSubscriber.php in the PR diff.
Source: mautic/mautic#17225
| .. vale on | ||
|
|
||
| The ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_TOGGLE_PUBLISH`` event dispatches when a User toggles the **Active** status of an Email. Mautic dispatches it before persisting the status change to the database, so Plugins can run actions or validations before the User activates or deactivates the Email. | ||
| The ``Mautic\EmailBundle\Event\EmailOnTogglePublishEvent`` event fires when a User toggles the **Active** status of an Email. Since Mautic 8.0, Mautic dispatches it by class name, before persisting the status change to the database, so Plugins can run actions or validations before the User activates or deactivates the Email. |
There was a problem hiding this comment.
Verified: new EmailOnTogglePublishEvent (final class extending EmailEvent) is dispatched by class name for the toggle-publish action; matches new file app/bundles/EmailBundle/Event/EmailOnTogglePublishEvent.php and its use as an array key ('on_toggle_publish' => EmailOnTogglePublishEvent::class) in the PR diff.
Source: mautic/mautic#17225
| { | ||
| return [ | ||
| EmailEvents::EMAIL_ON_TOGGLE_PUBLISH => ['onEmailTogglePublish', 0], | ||
| EmailOnTogglePublishEvent::class => ['onEmailTogglePublish', 0], |
There was a problem hiding this comment.
Verified: code sample keys getSubscribedEvents() on EmailOnTogglePublishEvent::class and getEmail() returns the Email entity, matching EmailEvent::getEmail() (app/bundles/EmailBundle/Event/EmailEvent.php) and the PR's own functional test (EventSubscriberSmokeTest / testTogglePublishEventIsDispatched).
Source: mautic/mautic#17225
| The ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_TOGGLE_PUBLISH`` event dispatches when a User toggles the **Active** status of an Email. Mautic dispatches it before persisting the status change to the database, so Plugins can run actions or validations before the User activates or deactivates the Email. | ||
| The ``Mautic\EmailBundle\Event\EmailOnTogglePublishEvent`` event fires when a User toggles the **Active** status of an Email. Since Mautic 8.0, Mautic dispatches it by class name, before persisting the status change to the database, so Plugins can run actions or validations before the User activates or deactivates the Email. | ||
|
|
||
| An event listener receives a ``Mautic\EmailBundle\Event\EmailOnTogglePublishEvent`` instance, a subclass of ``EmailEvent``. Call ``getEmail()`` to get the Email, then ``isPublished()`` on that Email entity to read its current **Active** status. |
There was a problem hiding this comment.
Verified: EmailOnTogglePublishEvent is final class EmailOnTogglePublishEvent extends EmailEvent {} (new file in PR). EmailEvent (app/bundles/EmailBundle/Event/EmailEvent.php) only exposes getEmail()/setEmail(), no isPublished(). isPublished() is defined on the Email entity's parent Mautic\CoreBundle\Entity\FormEntity, not on the event, confirming the doc's corrected instruction to call getEmail() then isPublished() on the returned Email entity. "Active" status matches the doc's own toggle-publish terminology used throughout this section (Toggle 'Active' event).
Source: mautic/mautic#17225
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, the build, send, and display events dispatch by class name, so key ``getSubscribedEvents()`` on ``EmailOnBuildEvent::class``, ``EmailSendEvent::class``, or ``EmailDisplayEvent::class``. Mautic renamed ``EmailBuilderEvent`` to ``EmailOnBuildEvent`` and removed the ``EMAIL_ON_BUILD`` and ``EMAIL_ON_DISPLAY`` constants, so code that still references ``EmailEvents::EMAIL_ON_BUILD`` or ``EmailEvents::EMAIL_ON_DISPLAY`` throws a PHP fatal error (``Error: Undefined constant``). The ``EMAIL_ON_SEND`` constant remains, but Mautic no longer dispatches by it, so a subscriber keyed on ``EmailEvents::EMAIL_ON_SEND`` silently stops firing — key on ``EmailSendEvent::class`` instead. |
There was a problem hiding this comment.
Verified against EmailEvents.php diff and UPGRADE-8.0.md removed-constants table: EMAIL_ON_BUILD and EMAIL_ON_DISPLAY constants are removed entirely (referencing them is now an undefined-class-constant fatal error). EMAIL_ON_SEND remains in EmailEvents.php (kept because it doubles as a webhook type identifier per UPGRADE-8.0.md), but MailHelper::dispatchSendEvent() now calls $this->dispatcher->dispatch($event) with no event-name argument, i.e. dispatch is keyed by class name only, so a subscriber still keyed on the string constant EmailEvents::EMAIL_ON_SEND no longer matches and silently stops receiving the event.
Source: mautic/mautic#17225
| An event listener receives a ``Mautic\EmailBundle\Event\EmailEvent`` instance. | ||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, this event dispatches by class name, so key ``getSubscribedEvents()`` on ``EmailOnTogglePublishEvent::class``. Mautic removed the ``EMAIL_ON_TOGGLE_PUBLISH`` constant, so code that still references ``EmailEvents::EMAIL_ON_TOGGLE_PUBLISH`` throws a PHP fatal error (``Error: Undefined constant``). |
There was a problem hiding this comment.
Verified: EmailEvents::EMAIL_ON_TOGGLE_PUBLISH constant is removed in the EmailEvents.php diff (also listed in the UPGRADE-8.0.md removed-constants table, mapped to the new EmailOnTogglePublishEvent class); referencing the removed constant is a PHP undefined-class-constant fatal error.
Source: mautic/mautic#17225
The Mautic 8.0 class-name event dispatch (PR mautic/mautic#17225) removed the EmailEvents::MONITORED_EMAIL_CONFIG constant. Update the monitored-inbox plugin example to key getSubscribedEvents() on MonitoredEmailEvent::class and add a note explaining the removed constant now throws a fatal error. The EMAIL_PRE_FETCH and EMAIL_PARSE events remain string-dispatched and unchanged.
| To do this, the Plugin needs to add an event listener for three events: | ||
|
|
||
| 1. ``EmailEvents::MONITORED_EMAIL_CONFIG`` This event is dispatched to inject the fields into Mautic's Configuration to configure the IMAP inbox and folder that should be monitored. | ||
| 1. ``Mautic\EmailBundle\Event\MonitoredEmailEvent`` This event injects the fields into Mautic's Configuration to configure the IMAP inbox and folder to monitor. Since Mautic 8.0, Mautic dispatches it by class name, so subscribers key on ``MonitoredEmailEvent::class``. |
There was a problem hiding this comment.
Verified: FQCN is Mautic\EmailBundle\Event\MonitoredEmailEvent (app/bundles/EmailBundle/Event/MonitoredEmailEvent.php:10, final class extends Event). Core's own ConfigMonitoredEmailType::buildForm() calls $this->dispatcher->dispatch($event); with no event-name argument (line 29), i.e. Symfony dispatches by the event's class name. This class-name dispatch predates PR #17225 (the file is untouched by the PR diff); PR #17225 removed the now-orphaned EmailEvents::MONITORED_EMAIL_CONFIG string constant that had never matched this call site's actual dispatch.
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, the monitored inbox configuration event dispatches by class name, so key ``getSubscribedEvents()`` on ``MonitoredEmailEvent::class``. Mautic removed the ``MONITORED_EMAIL_CONFIG`` constant, so code that still references ``EmailEvents::MONITORED_EMAIL_CONFIG`` throws a PHP fatal error (``Error: Undefined constant``). ``EMAIL_PRE_FETCH`` and ``EMAIL_PARSE`` remain string-dispatched constants. |
There was a problem hiding this comment.
Verified: UPGRADE-8.0.md "Removed code" table lists MONITORED_EMAIL_CONFIG -> MonitoredEmailEvent as a removed EmailEvents constant (line 38), and app/bundles/EmailBundle/EmailEvents.php at the PR head SHA confirms the constant is absent (referencing EmailEvents::MONITORED_EMAIL_CONFIG now throws PHP Error: Undefined constant). The same file's intro text (UPGRADE-8.0.md line 43) and EmailEvents.php (EMAIL_PARSE at line 30, EMAIL_PRE_FETCH at line 38) confirm both constants remain, and MonitoredEmail/Fetcher.php still dispatches by string via EmailEvents::EMAIL_PRE_FETCH (line 40) and EmailEvents::EMAIL_PARSE (line 68).
| EmailEvents::MONITORED_EMAIL_CONFIG => ['onConfig', 0], | ||
| EmailEvents::EMAIL_PRE_FETCH => ['onPreFetch', 0], | ||
| EmailEvents::EMAIL_PARSE => ['onParse', 0], | ||
| MonitoredEmailEvent::class => ['onConfig', 0], |
There was a problem hiding this comment.
Verified: the code sample's MonitoredEmailEvent::class => ['onConfig', 0] subscriber key matches the real pattern used by Mautic's own monitored-inbox subscribers (ProcessBounceSubscriber.php:20, and identically in ProcessReplySubscriber.php and ProcessUnsubscribeSubscriber.php), all of which key getSubscribedEvents() on MonitoredEmailEvent::class rather than a string constant.
adiati98
left a comment
There was a problem hiding this comment.
@promptless-for-oss please address the suggestions.
| ======================= | ||
|
|
||
| To render custom tokens, use the ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_SEND`` event when Mautic sends the Email, or the ``\Mautic\EmailBundle\EmailEvents::EMAIL_ON_DISPLAY`` event when the Email displays in a browser such as after the Contact clicks the ``{webview_url}`` link. | ||
| To render custom tokens, key on the ``Mautic\EmailBundle\Event\EmailSendEvent`` event (``EmailSendEvent::class``) when Mautic sends the Email, or the ``Mautic\EmailBundle\Event\EmailDisplayEvent`` event (``EmailDisplayEvent::class``) when the Email displays in a browser, for example, when the Contact clicks the ``{webview_url}`` link. |
There was a problem hiding this comment.
We use hyphen instead of parentheses.
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, the build, send, and display events dispatch by class name, so key ``getSubscribedEvents()`` on ``EmailOnBuildEvent::class``, ``EmailSendEvent::class``, or ``EmailDisplayEvent::class``. Mautic renamed ``EmailBuilderEvent`` to ``EmailOnBuildEvent`` and removed the ``EMAIL_ON_BUILD`` and ``EMAIL_ON_DISPLAY`` constants, so code that still references ``EmailEvents::EMAIL_ON_BUILD`` or ``EmailEvents::EMAIL_ON_DISPLAY`` throws a PHP fatal error (``Error: Undefined constant``). The ``EMAIL_ON_SEND`` constant remains, but Mautic no longer dispatches by it, so a subscriber keyed on ``EmailEvents::EMAIL_ON_SEND`` silently stops firing — key on ``EmailSendEvent::class`` instead. |
There was a problem hiding this comment.
We use hyphen instead of parentheses and em dash.
| 1. ``Mautic\EmailBundle\Event\MonitoredEmailEvent`` This event injects the fields into Mautic's Configuration to configure the IMAP inbox and folder to monitor. Since Mautic 8.0, Mautic dispatches it by class name, so subscribers key on ``MonitoredEmailEvent::class``. | ||
| 2. ``EmailEvents::EMAIL_PRE_FETCH`` This event is dispatched during the execution of the ``mautic:email:fetch`` command. It's used to inject search criteria for the messages desired. | ||
| 3. ``EmailEvents::EMAIL_PARSE`` This event parses the messages fetched by the command. |
There was a problem hiding this comment.
- Follow our guide to use
#.instead of number for ordered list. - Use active instead of passive voice.
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, the monitored inbox configuration event dispatches by class name, so key ``getSubscribedEvents()`` on ``MonitoredEmailEvent::class``. Mautic removed the ``MONITORED_EMAIL_CONFIG`` constant, so code that still references ``EmailEvents::MONITORED_EMAIL_CONFIG`` throws a PHP fatal error (``Error: Undefined constant``). ``EMAIL_PRE_FETCH`` and ``EMAIL_PARSE`` remain string-dispatched constants. |
There was a problem hiding this comment.
We use hyphen instead of parentheses.
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8.0, this event dispatches by class name, so key ``getSubscribedEvents()`` on ``EmailOnTogglePublishEvent::class``. Mautic removed the ``EMAIL_ON_TOGGLE_PUBLISH`` constant, so code that still references ``EmailEvents::EMAIL_ON_TOGGLE_PUBLISH`` throws a PHP fatal error (``Error: Undefined constant``). |
There was a problem hiding this comment.
We use hyphen instead of parentheses.
|
Thanks @adiati98 — on it. We'll apply your style fixes (hyphens instead of parentheses and em dashes, |
…tive voice Address CHANGES_REQUESTED on PR mautic#660 for docs/plugin_extensions/emails.rst: - Replace parenthetical asides with spaced hyphens (rendering-tokens sentence and the removed-constant notes) - Replace the em dash in the send/display note with a hyphen - Convert the monitored-inbox ordered list from 1./2./3. to #. - Rewrite items 2 and 3 of that list in active voice
|
Thanks for the review, @adiati98! I've addressed all the requested changes in
Code blocks, class names, constants, and the |
Open in Promptless
Mautic 8.0 dispatches the Email bundle's builder, send, display, and toggle-publish events by class name (Symfony 4.3 style), so Plugin subscribers must key
getSubscribedEvents()on the event class instead of anEmailEventsstring constant. This updates the Email plugin-extension guide (docs/plugin_extensions/emails.rst) so its token-registration, token-rendering, A/B-testing, and Toggle-'Active' examples key onEmailOnBuildEvent::class,EmailSendEvent::class,EmailDisplayEvent::class, andEmailOnTogglePublishEvent::class. It renames the removedEmailBuilderEventclass toEmailOnBuildEvent, clarifies that the send and display paths are now separate classes that must each be keyed, and adds two notes explaining the backward-compatibility break: referencing a removed constant throws a PHP fatal error, while a subscriber still keyed on the survivingEMAIL_ON_SENDconstant silently stops firing.The monitored-inbox example is also updated: Mautic 8.0 removed the
MONITORED_EMAIL_CONFIGconstant, so the subscriber now keys onMonitoredEmailEvent::class, with a note that referencing the removed constant throws a PHP fatal error. TheEMAIL_PRE_FETCHandEMAIL_PARSEevents remain string-dispatched and are unchanged.Trigger Events
Review response (@adiati98)
Thanks for the review! Addressed all requested changes in
docs/plugin_extensions/emails.rstand swept the rest of the diff for the same issues so nothing's left to re-flag:#.instead of numbers for the ordered list (applied verbatim): the monitored-inbox list now uses#.on all three items.mautic:email:fetchcommand. Use it to inject search criteria for the desired messages." and "This event parses the messages that the command fetched."Code blocks, class names, constants, and the
Error: Undefined constantstring are unchanged. Vale passes with no new violations.