Document Mautic 8.0 class-name dispatch for PageBundle events - #648
Document Mautic 8.0 class-name dispatch for PageBundle events#648promptless-for-oss wants to merge 1 commit into
Conversation
PR mautic/mautic#17203 dispatches PageDisplayEvent and TrackingEvent by their event-class name in Mautic 8.0. Update the plugin-extension and tracking-script subscriber examples to key getSubscribedEvents() on <Event>::class, and add notes explaining that a subscriber left on the old PageEvents::* constant silently stops receiving the event. Leave PAGE_ON_BUILD and PAGE_ON_TOGGLE_PUBLISH keyed on their string constants (shared PageEvent class) and note why.
| Preference Center lets Contacts manage their communication preferences. Since Mautic 7.2, you can customize the labels on Preference Center slot components using the Page display event. | ||
|
|
||
| .. vale on | ||
|
|
There was a problem hiding this comment.
Confirms Mautic 8.0 dispatches PageDisplayEvent by class name (Symfony 4.3+ style); subscribers must key on PageDisplayEvent::class; PageEvents::PAGE_ON_DISPLAY constant remains defined for backward compatibility but is no longer used to dispatch this event. Source: mautic/mautic PR #17203, UPGRADE-8.0.md mapping table and prose.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319
| return [ | ||
| PageEvents::PAGE_ON_BUILD => ['onPageBuild', 0], | ||
| PageEvents::PAGE_ON_DISPLAY => ['onPageDisplay', 0] | ||
| PageEvents::PAGE_ON_BUILD => ['onPageBuild', 0], |
There was a problem hiding this comment.
Confirms PageEvents::PAGE_ON_DISPLAY converts to PageDisplayEvent::class as a subscriber key; PAGE_ON_BUILD is not in the converted list (kept as string constant, shared PageEvent class). Source: mautic/mautic PR #17203, UPGRADE-8.0.md mapping table.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L327
| CoreEvents::BUILD_MAUTIC_JS => ['onBuildJs', 0], | ||
| PageEvents::ON_CONTACT_TRACKED => ['onContactTracked', 0], | ||
| CoreEvents::BUILD_MAUTIC_JS => ['onBuildJs', 0], | ||
| TrackingEvent::class => ['onContactTracked', 0], |
There was a problem hiding this comment.
Confirms PageEvents::ON_CONTACT_TRACKED converts to TrackingEvent::class as a subscriber key in Mautic 8.0. Source: mautic/mautic PR #17203, UPGRADE-8.0.md mapping table.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L330
| If you need to do something during the request to track the Contact through ``/mtc/event``, or append to the payload returned to the tracking code, which you can use from custom JavaScript injected through ``CoreEvents::BUILD_MAUTIC_JS``, subscribe to the tracking event with an :ref:`Event Listener<plugins/event_listeners:Event listeners>`. | ||
| The listener can inject a custom payload through the ``Mautic\PageBundle\Event\TrackingEvent::set`` method. | ||
| This will expose the payload to the tracking code's ``mauticPageEventDelivered`` event in the ``detail.response.events`` object. See the PHP code example. | ||
| This will expose the payload to the tracking code's ``mauticPageEventDelivered`` event in the ``detail.response.events`` object. See the PHP code example. |
There was a problem hiding this comment.
Confirms Mautic 8.0 dispatches TrackingEvent by class name; subscribers must key on TrackingEvent::class; PageEvents::ON_CONTACT_TRACKED constant remains defined for backward compatibility but no longer used to dispatch this event. Source: mautic/mautic PR #17203, UPGRADE-8.0.md.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319
|
|
||
| .. note:: | ||
|
|
||
| A subscriber left on the old ``PageEvents::PAGE_ON_DISPLAY`` constant silently stops receiving the event in Mautic 8.0, because Mautic raises no error to flag the change. Re-key it on ``PageDisplayEvent::class``, as shown above. |
There was a problem hiding this comment.
Confirms the silent-failure claim: PublicController dispatches PageDisplayEvent with $this->dispatcher->dispatch($event) (no event-name argument), so Symfony 4.3+ uses the event's FQCN as the dispatch name. A listener still keyed on the old PageEvents::PAGE_ON_DISPLAY string constant never matches this dispatch name and is simply never invoked - no exception, error, warning, or deprecation is raised by Mautic or Symfony's EventDispatcher for an unmatched listener registration. No BC-alias/deprecation-shim compiler pass exists in this PR mapping old PageEvents constants to the new FQCNs. See also UPGRADE-8.0.md (https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319) confirming the constants are kept for BC but no longer used internally.
|
|
||
| .. note:: | ||
|
|
||
| In Mautic 8.0, Mautic dispatches the ``PageDisplayEvent`` by its class name. Subscribers key ``getSubscribedEvents()`` on ``PageDisplayEvent::class``. A subscriber still keyed on the old ``PageEvents::PAGE_ON_DISPLAY`` string constant no longer receives the event in Mautic 8.0, even though ``PageEvents`` keeps the constant defined for backward compatibility. |
There was a problem hiding this comment.
Confirms Preference Center PageDisplayEvent dispatch (PublicController line 349-354) uses hasListeners(PageDisplayEvent::class) then dispatch($event) with no event-name argument, i.e. dispatched purely by FQCN. A subscriber still keyed on PageEvents::PAGE_ON_DISPLAY is never matched and never invoked; PageEvents keeps the constant defined for backward compatibility but it is no longer used internally (UPGRADE-8.0.md line 319: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319).
| * A/B test winning criteria | ||
|
|
||
| Both leverage the ``\Mautic\PageBundle\PageEvents::PAGE_ON_BUILD`` event. Read more about :ref:`plugins/event_listeners:Event listeners`. | ||
| Both use the ``\Mautic\PageBundle\PageEvents::PAGE_ON_BUILD`` event, and the tokens example below also handles the Page display event. In Mautic 8.0, the display event keys on ``PageDisplayEvent::class``, while ``PAGE_ON_BUILD`` stays keyed on its string constant. |
There was a problem hiding this comment.
Confirms PAGE_ON_BUILD is in the PageEvent group that UPGRADE-8.0.md explicitly lists as unchanged/staying as string constants because the event class (PageEvent) is shared by multiple constants (PAGE_ON_BUILD, PAGE_PRE_SAVE, PAGE_POST_SAVE, PAGE_PRE_DELETE, PAGE_POST_DELETE, PAGE_ON_TOGGLE_PUBLISH). PageModel::dispatchEvent still calls $this->dispatcher->dispatch($event, PageEvents::PAGE_ON_BUILD) with the explicit string-constant second argument (app/bundles/PageBundle/Model/PageModel.php line 775 at this commit), confirming the dispatch site itself is unconverted.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319
|
|
||
| .. note:: | ||
|
|
||
| ``PAGE_ON_TOGGLE_PUBLISH``, like ``PAGE_ON_BUILD``, dispatches the shared ``PageEvent`` class that several event names reuse, so it stays keyed on its ``PageEvents::*`` string constant. Only events with a dedicated event class, such as ``PageDisplayEvent``, changed to class-name keying in Mautic 8.0. |
There was a problem hiding this comment.
Confirms PAGE_ON_TOGGLE_PUBLISH and PAGE_ON_BUILD both dispatch the shared Mautic\PageBundle\Event\PageEvent class and therefore stay keyed on their PageEvents::* string constants per UPGRADE-8.0.md's explicit "Constants that share an event class stay as string constants: the PageEvent group (PAGE_ON_BUILD, PAGE_PRE_SAVE, PAGE_POST_SAVE, PAGE_PRE_DELETE, PAGE_POST_DELETE, PAGE_ON_TOGGLE_PUBLISH) ... are unchanged" statement. PageModel.php dispatch sites (lines 285 and 775 at this commit) still pass the PageEvents::* constant explicitly as the dispatch event name, confirming these were not converted to class-name keying.
Source: https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319
|
|
||
| .. note:: | ||
|
|
||
| In Mautic 8.0, ``TrackingEvent`` dispatches by its class name, so the subscriber keys ``getSubscribedEvents()`` on ``TrackingEvent::class``, as shown. A subscriber left on the old ``PageEvents::ON_CONTACT_TRACKED`` constant silently stops receiving it, and Mautic raises no error. See :ref:`hooking into the tracking process<mauticjs_api/tracking_script:Hooking into the tracking process and returning custom responses>` for the full explanation. |
There was a problem hiding this comment.
Confirms the silent-failure claim for TrackingEvent: PublicController dispatches with $this->dispatcher->dispatch($event) (no event-name argument), so Symfony uses TrackingEvent::class (FQCN) as the dispatch name. A subscriber still keyed on PageEvents::ON_CONTACT_TRACKED never matches and is never called - Mautic raises no error, warning, or deprecation. No BC-alias/deprecation-shim compiler pass exists in this PR mapping the old constant to the new FQCN. Corroborated by UPGRADE-8.0.md line 319 (https://github.com/mautic/mautic/blob/e7cec3eb13092892f3b373207f212835c4cedee5/UPGRADE-8.0.md#L319), which states the PageEvents constants are kept for backwards compatibility but no longer used internally.
|
|
||
| .. note:: | ||
|
|
||
| In Mautic 8.0, Mautic dispatches the ``TrackingEvent`` by its class name. Subscribers key ``getSubscribedEvents()`` on ``TrackingEvent::class``. A subscriber still keyed on the old ``PageEvents::ON_CONTACT_TRACKED`` string constant no longer receives the event in Mautic 8.0, even though ``PageEvents`` keeps the constant defined for backward compatibility. The failure is silent. Mautic raises no error, warning, or deprecation, and the subscriber method attached to the old key never runs. |
There was a problem hiding this comment.
Confirms the detailed silent-failure claim ("no error, warning, or deprecation, and the subscriber method attached to the old key simply never runs"). TrackingEvent is dispatched via a single-argument dispatch($event) call, so Symfony resolves the dispatch name as the event's FQCN (Symfony 4.3+ behavior); there is no alias/BC compiler pass bridging PageEvents::ON_CONTACT_TRACKED to TrackingEvent::class in this PR, and Symfony's EventDispatcher does not emit any error/warning/deprecation when a registered listener's name simply does not match a dispatched event's name - dispatching with zero matching listeners is normal, silent behavior. PageEvents::ON_CONTACT_TRACKED remains a valid, defined PHP constant (Mautic\PageBundle\PageEvents, 'mautic.page.on_contact_tracked') so no fatal/undefined-constant error occurs either.
1 participant
Open in Promptless
Mautic 8.0 (mautic/mautic PR #17203) dispatches several PageBundle events by their event-object class name instead of the
Mautic\PageBundle\PageEventsstring constants, following the Symfony 4.3+ convention. This updates the developer-documentation subscriber examples so plugin developers use the key form that actually fires in 8.0, and warns anyone with an existing subscriber that it must be re-keyed.plugin_extensions/landing_pages.rst: thePageDisplayEventsubscriber examples (PageSubscriber and PreferenceCenterSubscriber) now keygetSubscribedEvents()onPageDisplayEvent::class, with notes explaining that a subscriber left on the oldPageEvents::PAGE_ON_DISPLAYconstant silently stops receiving the event (Mautic raises no error). A note in the Toggle 'Available for use' section explains thatPAGE_ON_TOGGLE_PUBLISHandPAGE_ON_BUILDstay keyed on their string constants because they dispatch the sharedPageEventclass.mauticjs_api/tracking_script.rst: the TrackingSubscriber example now keys onTrackingEvent::class, with a matching note.The
PageEventsconstants remain defined for backward compatibility but are no longer used internally to dispatch these events.Trigger Events