Events and observers
Overview
Working with events and observers is one of the main ways to extend Magento functionality. The events and observers implementation in Magento 2 is based on the publish-subscribe pattern. Using events and observers, you can run your custom code in response to a specific Magento event or even a custom event.
Events
Events are dispatched by modules when certain actions are triggered. In addition to its own events, Magento allows you to create your own events that can be dispatched in your code. When an event is dispatched, it can pass data to any observers configured to watch that event.
Dispatching events
Events can be dispatched using the Magento\Framework\Event\ManagerInterface
class. This class can be obtained through dependency injection by defining the dependency in your constructor.
To dispatch an event, call the dispatch
function of the event manager class and provide it with the name of the event you want to dispatch along with an array of data you wish to provide to observers.
The following example shows you how to dispatch an event with and without an array of data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace MyCompany\MyModule;
use Magento\Framework\Event\ManagerInterface as EventManager;
class MyClass
{
/**
* @var EventManager
*/
private $eventManager;
/*
* @param EventManager $eventManager
*/
public function __construct(EventManager $eventManager)
{
$this->eventManager = $eventManager;
}
public function something()
{
$eventData = null;
// Code...
$this->eventManager->dispatch('my_module_event_before');
// More code that sets $eventData...
$this->eventManager->dispatch('my_module_event_after', ['myEventData' => $eventData]);
}
}
Creating new events
Custom events can be dispatched by simply passing in a unique event name to the event manager when you call the dispatch
function. Your unique event name is referenced in your module’s events.xml
file where you specify which observers will react to that event.
You can make the custom event my_module_event_after
subscribable by declaring the MyCompany/MyModule/etc/events.xml
file as follows:
1
2
3
4
5
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
<event name="my_module_event_after">
<observer name="my_module_event_after_observer" instance="MyCompany\MyModule\Observer\MyEvent"/>
</event>
</config>
Event areas
Generally, the location of the events.xml
file will be under the <module-root>/etc
directory. Observers that are associated with events here will watch for these events globally. The events.xml
file can also be defined under the <module-root>/etc/frontend
and <module-root>/etc/adminhtml
directories to configure observers to only watch for events in those specific areas.
Declare the observer in the appropriate area. The global
area allows the observer to run in all areas (adminhtml
, crontab
, frontend
, graphql
, webapi_rest
, webapi_soap
).
Area | File location |
---|---|
global |
<module-dir>/etc/events.xml |
adminhtml |
<module-dir>/etc/adminhtml/events.xml |
crontab |
<module-dir>/etc/crontab/events.xml |
frontend |
<module-dir>/etc/frontend/events.xml |
graphql |
<module-dir>/etc/graphql/events.xml |
webapi_rest |
<module-dir>/etc/webapi_rest/events.xml |
webapi_soap |
<module-dir>/etc/webapi_soap/events.xml |
Observers
Observers are a certain type of Magento class that can influence general behavior, performance, or change business logic. Observers are executed whenever the event they are configured to watch is dispatched by the event manager.
Creating an observer
To create an observer, you must place your class file under your <module-root>/Observer
directory. Your observer class should implement Magento\Framework\Event\ObserverInterface
and define its execute
function.
Below is an example of the basic observer class structure:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace MyCompany\MyModule\Observer;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
class MyObserver implements ObserverInterface
{
public function __construct()
{
// Observer initialization code...
// You can use dependency injection to get any class this observer may need.
}
public function execute(Observer $observer)
{
// Observer execution code...
}
}
One of the more powerful feature of observers is that they are able to use parameters passed into the event when it was dispatched. Below is an example of an observer obtaining data passed in when the event was dispatched.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?php
/**
* Copyright © Magento, Inc. All rights reserved.
* See COPYING.txt for license details.
*/
namespace MyCompany\MyModule\Observer;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
class AnotherObserver implements ObserverInterface
{
public function __construct()
{
// Observer initialization code...
// You can use dependency injection to get any class this observer may need.
}
public function execute(Observer $observer)
{
$myEventData = $observer->getData('myEventData');
// Additional observer execution code...
}
}
Subscribing to events
Observers can be configured to watch certain events in the events.xml
file.
The observer
xml element has the following properties:
name
(required) - The name of the observer for the event definition.instance
(required) - The fully qualified class name of the observer.disabled
- Determines whether this observer is active or not. Default value is false.shared
- Determines the lifestyle of the class. Default istrue
.
The observer name must be unique, or an override will occur.
Below is an example of how to assign observers to watch certain events:
1
2
3
4
5
6
7
8
9
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
<event name="my_module_event_before">
<observer name="myObserverName" instance="MyCompany\MyModule\Observer\MyObserver" />
</event>
<event name="my_module_event_after">
<observer name="myObserverName" instance="MyCompany\MyModule\Observer\AnotherObserver" />
</event>
</config>
In the preceding example, we assign the observer MyObserver
to the custom event my_module_event_before
and AnotherObserver
to my_module_event_after
.
Observer names must be unique per event definition. This means that you cannot have two observers with the same name in the same event definition. In the example, both observers have the name myObserverName
. This is acceptable because each of those observers belong to different event definitions.
If you declare an observer with a name that is already in use within the same event, Magento merges these declaration nodes into a single observer declaration, respecting the module load order as defined in the app/etc/config.php
file. This is useful when disabling an observer declared in another module.
Disabling an observer
Existing observers can be disabled, if you do not want to have them running. It is a good practice to disable the obsever if you want to change its logic rather than override it. Below is an example of how to disable the previously created observer.
1
2
3
4
5
6
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
<event name="my_module_event_before">
<observer name="myObserverName" disabled="true" />
</event>
</config>