Document Mautic 8 class-name dispatch for Email, Point, User, API, and Category bundle events - #652
Conversation
…d Category bundle events Mautic 8 (mautic/mautic#17217) migrates selected bundle events from *Events string-constant dispatch to Symfony 4.3+ class-name dispatch. Update the two documented subscriber examples that reference converted events (MonitoredEmailEvent, ApiPlatformPermissionContextEvent) to key getSubscribedEvents() on EventClass::class, add migration notes and debug:event-dispatcher verification tips, and correct the blanket 'always use the event constants' advice on the Available events page.
|
|
||
| .. note:: | ||
|
|
||
| Since Mautic 8, ``MonitoredEmailEvent`` is dispatched by the event object alone. Key ``getSubscribedEvents()`` on ``MonitoredEmailEvent::class``, not on ``EmailEvents::MONITORED_EMAIL_CONFIG`` or the string ``mautic.monitored_email_config``. The constant remains for backward compatibility but no longer dispatches this event, so a subscriber still keyed on ``EmailEvents::MONITORED_EMAIL_CONFIG`` never fires—no exception is thrown and nothing is logged. Only ``MONITORED_EMAIL_CONFIG`` changed: ``EmailEvents::EMAIL_PRE_FETCH`` and ``EmailEvents::EMAIL_PARSE`` still dispatch by their string constants, so keep subscribing to those two on the constants. |
There was a problem hiding this comment.
PR mautic/mautic#17217 (open, head 2400aa56dc5df5489fbbac88aca01bf146a6bf94) converts EmailBundle's dispatch of the MonitoredEmailEvent from EmailEvents::MONITORED_EMAIL_CONFIG (string 'mautic.monitored_email_config', see EmailEvents.php L113) to bare dispatch($event), i.e. class-name dispatch on Mautic\EmailBundle\Event\MonitoredEmailEvent. The constant is kept only for BC and no longer matches the dispatched event name. EMAIL_PRE_FETCH ('mautic.on_email_pre_fetch', EmailEvents.php L128) and EMAIL_PARSE ('mautic.on_email_parse', EmailEvents.php L120) are unchanged by this PR and still dispatch by their string constants.
|
|
||
| .. code-block:: console | ||
|
|
||
| bin/console debug:event-dispatcher 'Mautic\EmailBundle\Event\MonitoredEmailEvent' |
There was a problem hiding this comment.
Confirms bin/console debug:event-dispatcher is a real Symfony console command that accepts an event name or FQCN argument (e.g. debug:event-dispatcher 'Mautic\EmailBundle\Event\MonitoredEmailEvent') and lists listeners registered for it, including class-based event names.
Source: https://symfony.com/doc/current/components/event_dispatcher.html
| * - ``ApiEvents::API_PLATFORM_PERMISSION_CONTEXT`` | ||
| - Mautic dispatches this before API Platform evaluates authorization. The event string is ``mautic.api_platform_permission_context``. | ||
| * - ``ApiPlatformPermissionContextEvent`` | ||
| - Since Mautic 8, Mautic dispatches this event by its class rather than a string constant, before API Platform evaluates authorization. The ``ApiEvents::API_PLATFORM_PERMISSION_CONTEXT`` constant remains for backward compatibility. |
There was a problem hiding this comment.
PR mautic/mautic#17217 (open, head 2400aa56dc5df5489fbbac88aca01bf146a6bf94) converts ApiBundle's dispatch of ApiPlatformPermissionContextEvent (FQCN Mautic\ApiBundle\Event\ApiPlatformPermissionContextEvent) from ApiEvents::API_PLATFORM_PERMISSION_CONTEXT (string value 'mautic.api_platform_permission_context', see ApiEvents.php L70) to bare dispatch($permissionContextEvent), i.e. class-name dispatch. Same change applied in ApiPermissionVoter.php. The constant is kept only for BC and no longer matches the dispatched event name; no dual/BC dispatch to the old string was added.
|
|
||
| .. code-block:: console | ||
|
|
||
| bin/console debug:event-dispatcher 'Mautic\ApiBundle\Event\ApiPlatformPermissionContextEvent' |
There was a problem hiding this comment.
Confirms bin/console debug:event-dispatcher accepts a specific event name/FQCN argument (e.g. debug:event-dispatcher 'Mautic\ApiBundle\Event\ApiPlatformPermissionContextEvent') and lists its registered listeners.
Source: https://symfony.com/doc/current/components/event_dispatcher.html
| **************** | ||
|
|
||
| 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. | ||
| 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. For events still dispatched by their string name, always use the event constants to ensure future changes to event names won't break the Plugin. Since Mautic 8, several bundles dispatch selected events by the event object's class instead of by a string constant. Core, Report, Stage, Dashboard, and SMS made this change earlier. Email, Point, User, API, and Category each convert selected events the same way, so only some events within those bundles moved to class dispatch. To confirm which name Mautic uses for a given event, see that bundle's extension documentation or the event's dispatch call. For those events, key ``getSubscribedEvents()`` on ``EventClass::class`` rather than the old ``*Events`` constant, because the constant's value no longer matches the dispatched event name. If you're unsure whether a given event has converted, run ``bin/console debug:event-dispatcher`` with the event name or class. Your subscriber appears in the listing only when it's keyed on the name Mautic actually dispatches. |
There was a problem hiding this comment.
PR #17217 (open) converts selected events in EmailBundle, PointBundle, UserBundle, ApiBundle, and CategoryBundle to class-name dispatch. Sibling merged PRs corroborate the other bundles named in the doc: #17157 (CoreBundle, and touches many other bundles), #17200 (ReportBundle), #17216 (Dashboard, Stage, Sms, and Notification bundles).
Source: mautic/mautic#17217
adiati98
left a comment
adiati98
left a comment
There was a problem hiding this comment.
@promptless-for-oss please address the Vale warnings.
|
Thanks @adiati98 — on it. I'll run Vale on the changed RST files, fix the flagged warnings, and push the update to this PR shortly. |
…c 8 dispatch notes Rewrites the passive constructions Vale (Google.Passive) flagged on the lines this PR changed in the Monitored Inbox and API permission-context sections. Names Mautic as the actor and the old-to-new dispatch contrast (class vs. string constant); technical meaning is unchanged.
|
Done @adiati98 — addressed the Vale warnings on the changed lines by converting the flagged passive voice to active in |
3 participants
Open in Promptless
Mautic 8 continues migrating bundle events from
*Eventsstring-constant dispatch to native Symfony 4.3+ class-name dispatch (source PR mautic/mautic#17217, following the same pattern as the already-documented Core, Report, Stage, Dashboard, and SMS bundles). For a converted event, Mautic now dispatches by the event object alone, so plugin developers must keygetSubscribedEvents()on the event class rather than the old constant. The*Eventsconstants remain defined for backward compatibility but no longer dispatch these events — a subscriber still keyed on the old constant silently stops firing, with no exception and nothing logged.This updates the two subscriber examples in the developer docs that reference a converted event —
MonitoredEmailEventin the Monitored Inbox Integration section andApiPlatformPermissionContextEventin the API permission-context event section — to key onEventClass::class, adds a migration note and abin/console debug:event-dispatcherverification tip to each, and corrects the now-inaccurate blanket "always use the event constants" guidance on the Available events page. Of the eleven events this PR converts, these are the only two currently documented with a subscriber example; the Email note also flags thatEMAIL_PRE_FETCHandEMAIL_PARSEin the same subscriber are unchanged and keep their string constants.Files touched:
docs/plugin_extensions/emails.rst,docs/plugin_extensions/api.rst,docs/plugins/event_listeners.rst.Trigger Events