Events and observers

Working with events and observers is one of the main ways to extend Adobe Commerce and Magento Open Source functionality. The events and observers implementation in Adobe Commerce and Magento Open Source are based on the publish-subscribe pattern. Using events and observers, you can run your custom code in response to a specific event or even a custom event.

Adobe Commerce developers can use the following event-driven technologies to create the next generation of apps and extensions:

Adobe I/O Events for Adobe Commerce allows you to send events asynchronously to applications built with Adobe App Builder. This feature is available on Adobe Commerce 2.4.4 and higher.
Adobe Commerce Webhooks enables you to synchronously send webhook calls to an external server for immediate processing. Webhooks are triggered by events and cancel the action that initiated the event if the external call does not succeed. This feature is available as of Adobe Commerce 2.4.4 and higher.

Events

Events are dispatched by modules when certain actions are triggered. In addition to its own events, the application 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.

<?php
/**
 * Copyright &copy; 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]);
    }
}

Copied to your clipboard
<?php
/**
 * Copyright &copy; 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:

<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>
Copied to your clipboard
<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 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:

<?php
/**
 * Copyright &copy; 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...
    }
}
Copied to your clipboard
<?php
/**
 * Copyright &copy; 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 features 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.

<?php
/**
 * Copyright &copy; 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...
    }
}
Copied to your clipboard
<?php
/**
 * Copyright &copy; 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 is true.

The observer name must be unique, or an override will occur.

Below is an example of how to assign observers to watch certain events:

<?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>
Copied to your clipboard
<?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, the application 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 observer if you want to change its logic rather than override it. Below is an example of how to disable the previously created observer.

<?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>
Copied to your clipboard
<?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>