From 5e1cbf67e2369633383de9801dbcd504d638146f Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Mon, 7 Oct 2024 22:56:50 +0100 Subject: [PATCH 01/18] Update event_listeners.rst Documentation for Event Listeners component #215 --- docs/plugins/event_listeners.rst | 151 +++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index af774c4f..3f756c1a 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -1,2 +1,153 @@ Event listeners =============== + +Mautic leverages Symfony's EventDispatcher to execute and communicate various actions through Mautic. Plugins can hook into these to extend the functionality of Mautic. Refer to the Extending Mautic section of the documentation for some of the ways to do this. + +.. code-block:: php + + array('onLeadPostSave', 0), + LeadEvents::LEAD_POST_DELETE => array('onLeadDelete', 0) + ); + } + + public function onLeadPostSave(LeadEvent $event) + { + $lead = $event->getLead(); + + // do something + } + + public function onLeadDelete(LeadEvent $event) + { + $lead = $event->getLead(); + + $deletedId = $lead->deletedId; + + // do something + } + } + // ... + +Subscribers +----------- +The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in `Symfony's documentation`_. + +Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the bundles's config file. See :ref:`plugins/config:Service config items` for more information on registering event services. + +Available Events +---------------- +There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle's *Event.php file in the root of the bundle. For example, Lead related events are defined and described in ``app\bundles\LeadBundle\LeadEvents.php``. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not break the plugin. + +Custom Events +------------- +A plugin can create and dispatch its own events. + +Custom events require the following: + +1) The class defining the available events for the plugin using a ``final class`` with constants. + +.. code-block:: php + + world = $world; + } + + public function shouldPanic() + { + return ('earth' == $this->world->getName()); + } + + public function setIsFalseAlarm() + { + $this->falseAlarm = true; + } + + public function getIsFalseAlarm() + { + return $this->falseAlarm; + } + } + // ... + + +3) The code that dispatches the event where appropriate using the ``event_dispatcher`` service. + +.. code-block:: php + + get('event_dispatcher'); + if ($dispatcher->hasListeners(HelloWorldEvents::ARMAGEDDON)) { + $event = $dispatcher->dispatch(HelloWorldEvents::ARMAGEDDON, new ArmageddonEvent($world)); + + if ($event->shouldPanic()) { + throw new \Exception("Run for the hills!"); + } + } + + From f32a4674fbfe131cbfd8ff35bfe8652ce998f130 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 07:58:29 +0100 Subject: [PATCH 02/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 3f756c1a..92f2caf7 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -1,7 +1,7 @@ Event listeners =============== -Mautic leverages Symfony's EventDispatcher to execute and communicate various actions through Mautic. Plugins can hook into these to extend the functionality of Mautic. Refer to the Extending Mautic section of the documentation for some of the ways to do this. +Mautic leverages Symfony's EventDispatcher to execute and communicate various actions through Mautic. Plugins can hook into these to extend the capability of Mautic. Refer to the Extending Mautic section of the documentation for some of the ways to do this. .. code-block:: php From c922ada0e7f7e0c14500a94ae42f370a1df27470 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 07:58:53 +0100 Subject: [PATCH 03/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 92f2caf7..4ac6698b 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -54,7 +54,7 @@ Subscribers ----------- The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in `Symfony's documentation`_. -Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the bundles's config file. See :ref:`plugins/config:Service config items` for more information on registering event services. +Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services. Available Events ---------------- From 4a740237511fd3187f8dc5291f3f2f9f6b463cb5 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 07:59:15 +0100 Subject: [PATCH 04/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 4ac6698b..acc1cbeb 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -56,7 +56,7 @@ The easiest way to listen to various events is to use an event subscriber. Read Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services. -Available Events +Available events ---------------- There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle's *Event.php file in the root of the bundle. For example, Lead related events are defined and described in ``app\bundles\LeadBundle\LeadEvents.php``. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not break the plugin. From 7ff45768c3340d45a2ee5bb55393e0dbc4dfb999 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 07:59:43 +0100 Subject: [PATCH 05/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index acc1cbeb..a843080d 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -58,6 +58,7 @@ Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSub Available events ---------------- + There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle's *Event.php file in the root of the bundle. For example, Lead related events are defined and described in ``app\bundles\LeadBundle\LeadEvents.php``. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not break the plugin. Custom Events From 5bb7f445d4f53b9bb2b7dd356176ad476cf98507 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:00:15 +0100 Subject: [PATCH 06/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index a843080d..b73dcb1e 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -59,6 +59,7 @@ Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSub Available events ---------------- + There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle's *Event.php file in the root of the bundle. For example, Lead related events are defined and described in ``app\bundles\LeadBundle\LeadEvents.php``. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not break the plugin. Custom Events From 9c985f5a2cd2c39ca1bb940cee3c5cfa744c5ab7 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:01:22 +0100 Subject: [PATCH 07/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index b73dcb1e..d5df1415 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -60,7 +60,7 @@ Available events ---------------- -There are many events available throughout Mautic. Depending on the desired functionality, look at the core bundle's *Event.php file in the root of the bundle. For example, Lead related events are defined and described in ``app\bundles\LeadBundle\LeadEvents.php``. The final classes provide the names of the events to listen to. Always use the event constants to ensure future changes to event names will not 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. Always use the event constants to ensure future changes to event names won't break the Plugin. Custom Events ------------- From 3b3c32b6ad25107ad07b3ddbd5b83d7791dc4f76 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:01:53 +0100 Subject: [PATCH 08/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index d5df1415..87f44ebd 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -64,7 +64,7 @@ There are many events available throughout Mautic. Depending on what you're tryi Custom Events ------------- -A plugin can create and dispatch its own events. +A Plugin can create and dispatch its own events. Custom events require the following: From e36ad8c7f9a84afcd06587154a2c1d08430bde50 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:02:23 +0100 Subject: [PATCH 09/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 87f44ebd..92f99d99 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -68,7 +68,7 @@ A Plugin can create and dispatch its own events. Custom events require the following: -1) The class defining the available events for the plugin using a ``final class`` with constants. +1) The class defining the available events for the Plugin using a ``final class`` with constants. .. code-block:: php From 85d9f277d3517ef2604a9b5e30d9485f7d314e1d Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:02:55 +0100 Subject: [PATCH 10/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 92f99d99..82f0473f 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -94,7 +94,7 @@ Custom events require the following: // ... -2) The Event class that is received by the listeners. This class should extend ``Symfony\Component\EventDispatcher\Event``. It will be created when the event is dispatched and should have any information listeners need to act on it. +2) The Event class that is received by the listeners. This class should extend ``Symfony\Component\EventDispatcher\Event``. It's created when the event is dispatched and should have any information listeners need to act on it. .. code-block:: php From 46f4ed4d191bd7a43902c9bdea527290dda89782 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:03:33 +0100 Subject: [PATCH 11/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 82f0473f..04844c2f 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -62,7 +62,7 @@ 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. -Custom Events +Custom events ------------- A Plugin can create and dispatch its own events. From 4606a23695f56bb073e8569e8986e057875f7673 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 09:54:48 +0100 Subject: [PATCH 12/18] Update event_listeners.rst referenced Symfony's docs event subscribers link file --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 04844c2f..540f92ba 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -52,7 +52,7 @@ Mautic leverages Symfony's EventDispatcher to execute and communicate various ac Subscribers ----------- -The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in `Symfony's documentation`_. +The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in :xref:`symfony-event-subscribers`. Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services. From 41be9fee55dcc27fc29b96ff4cc61a4719b27bf7 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Tue, 8 Oct 2024 09:55:32 +0100 Subject: [PATCH 13/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 540f92ba..069e8393 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -60,6 +60,7 @@ 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. Custom events From 25e62ff831e92d5248a474ce838819d944c28fca Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:25:37 +0100 Subject: [PATCH 14/18] Update docs/plugins/event_listeners.rst correct heading syntax Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 069e8393..86a31ca4 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -1,5 +1,5 @@ Event listeners -=============== +############### Mautic leverages Symfony's EventDispatcher to execute and communicate various actions through Mautic. Plugins can hook into these to extend the capability of Mautic. Refer to the Extending Mautic section of the documentation for some of the ways to do this. From 4b19aa8a7bddee774e80b1842917411daa8e5924 Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:25:59 +0100 Subject: [PATCH 15/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 86a31ca4..a4ae1340 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -57,7 +57,7 @@ The easiest way to listen to various events is to use an event subscriber. Read Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services. Available events ----------------- +**************** From c7152fa23754ee63427d6a98f2d28fc2800a1a2d Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:26:21 +0100 Subject: [PATCH 16/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index a4ae1340..caf13ba5 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -64,7 +64,7 @@ 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. Custom events -------------- +************* A Plugin can create and dispatch its own events. Custom events require the following: From 94f0436b47afcf399c48334e91d9356c02139b7d Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:28:21 +0100 Subject: [PATCH 17/18] Update docs/plugins/event_listeners.rst Co-authored-by: Ruth Cheesley --- docs/plugins/event_listeners.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index caf13ba5..13f9491d 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -51,7 +51,7 @@ Mautic leverages Symfony's EventDispatcher to execute and communicate various ac // ... Subscribers ------------ +*********** The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in :xref:`symfony-event-subscribers`. Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services. From 8bb84013d96a056539678d55cfb7c77333aefe7d Mon Sep 17 00:00:00 2001 From: Ife <64481442+ifeoluwafavour@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:32:54 +0100 Subject: [PATCH 18/18] Update event_listeners.rst changed to unique heading name instead of 'subscribers' --- docs/plugins/event_listeners.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/plugins/event_listeners.rst b/docs/plugins/event_listeners.rst index 13f9491d..94c3b5c0 100644 --- a/docs/plugins/event_listeners.rst +++ b/docs/plugins/event_listeners.rst @@ -50,8 +50,8 @@ Mautic leverages Symfony's EventDispatcher to execute and communicate various ac } // ... -Subscribers -*********** +Event subscribers +***************** The easiest way to listen to various events is to use an event subscriber. Read more about subscribers in :xref:`symfony-event-subscribers`. Plugin event subscribers can extend ``\Mautic\CoreBundle\EventListener\CommonSubscriber`` which gives access to commonly used dependencies and also allows registering the subscriber service through the config file for the bundle. See :ref:`plugins/config:Service config items` for more information on registering event services.