Events and Observers in Magento

Events in Magento are triggers that tell the system to look for subscribers, which must be executed when an event is fired. To fire an event you need to specify an event code – a string, e.g. my_custom_event_code. The event code should be descriptive. If the event is distinct, its code must be unique in the system. Optionally you can pass some data along with the event. We will talk about passing data with the event in detail a bit later. An example of an event fired in Magento:

Mage::dispatchEvent('event_code', array('myObject' => $myObject));

Event subscribers in Magento are class functions, which are defined in the <observers> node of the system configuration. Every time an event is fired, the system tries to locate these subscribers and execute their code. By convention, subscribers are implemented in classes, whose names contain the word observer. As an example let’s consider a core module Mage_SalesRule. In its Model folder you can find a file called Observer.php containing a class Mage_SalesRule_Model_Observer. An observer class does not have to extend any other class in a way the models usually extend Mage_Core_Model_Abstract. However, if the situation dictates, you are free to implement an observer as an extension of some other class. The function Mage_SalesRule_Model_Observer::sales_order_afterPlace is an example of an event subscriber. It is registered to observe event sales_order_place_after, which is fired right after an order is placed – in function Mage_Sales_Model_Order::place().

<global> <!-- this node can be <frontend> or <adminhtml> -->
        <events>
                <event_code> <!-- replace event_name with an event identifier, e.g. sales_order_place_after -->
                        <observers>
                                <your_observer_node_name> <!-- a custom identifier for your observer configuration -->
                                        <class>yourpackage_yourmodule/observer</class> <!-- a pointer to your observer model -->
                                        <method>yourObserverFunctionName</method> <!-- name of the function in your observer class -->
                                        <type>singleton</type> <!-- optional node defining how the observer class is instantiated -->
                                </your_observer_node_name>
                        </observers>
                </event_code>
        </events>
</global>

<type>model</type>

<global>
    <!-- some nodes omitted -->
    <events>
        <sales_order_place_after>
            <observers>
                <salesrule>
                    <class>salesrule/observer</class>
                    <method>sales_order_afterPlace</method>
                </salesrule>
            </observers>
        </sales_order_place_after>
        <sales_quote_config_get_product_attributes>
            <observers>
                <salesrule>
                    <class>salesrule/observer</class>
                    <method>addProductAttributes</method>
                </salesrule>
            </observers>
        </sales_quote_config_get_product_attributes>
        <sales_convert_quote_to_order>
            <observers>
                <salesrule>
                    <class>salesrule/observer</class>
                    <method>addSalesRuleNameToOrder</method>
                </salesrule>
            </observers>
        </sales_convert_quote_to_order>
    </events>
        <!-- some nodes omitted -->
</global>

Observer Functions and Passing Event Objects to Observers

Observer functions take one parameter – $observer of type Varien_Event_Observer. Its primary role is to pass data from the code that fired the event to the observer function. For this purpose the class Varien_Event_Observer has a data property event. This property is an object of class Varien_Event and it contains the data, which was passed along with the fired event. Staying with our example, after an order is placed the system fires a sales_order_place_after event:

Mage::dispatchEvent('sales_order_place_after', array('order' => $this));

Here $this is the order object itself. It is passed on to the observer function in an associative array. Its key is ‘order’ – and under this identifier the order object will be available to the observer function. You can pass several objects or variables to the observer function by adding more elements to that array, e.g.:

Mage::dispatchEvent(
    'sales_order_place_after',
    array('order' => $this, 'checkout' => Mage::getSingleton('checkout/session')
);

This will pass the order object and a checkout session singleton to the observer function.

The observer function uses its parameter $observer to extract the data passed for processing:

public function sales_order_afterPlace($observer)
{
        $order = $observer->getEvent()->getOrder();
        /** code omitted for brevity **/
}

As you can see, $observer returns an object of type Varien_Event that it has in its data storage like any other object inherited from the class Varien_Object. The Varien_Event in turn, returns the order object passed by the code that fired the event. The order is also stored in the data and is retrieved by the magic getter function.

Dispatch Event Flow

The event processing starts with some code in Magento calling Mage::dispatchEvent($eventName, $args);. In this call $eventName is a string containing a unique event identifier. The parameter $args is an associative array. Its keys are names by which the objects (elements of the array) can be referred to in the function that catches and processes the event. For example, the model Mage_Sales_Model_Order dispatches events sales_order_place_before and sales_order_place_after from its function place():

public function place()
{
        Mage::dispatchEvent('sales_order_place_before', array('order'=>$this));
        $this->_placePayment();
        Mage::dispatchEvent('sales_order_place_after', array('order'=>$this));
        return $this;
}

The second parameter in these calls contains the order object itself. This way any function, which is subscribed to these events, can access the properties of the object that has triggered them.

The function Mage::dispatchEvent doesn’t do much itself. It delegates the event broadcasting to a function under the same name in the Mage_Core_Model_App class. The function Mage_Core_model_App::dispatchEvent loops through the internal event configuration storage of the app singleton. Depending on where in the application the event was fired, this configuration can include global observers only, or global and either frontend or adminhtml observers. If a match is found the system creates an instance of the observer class (it can be a regular model object or a singleton depending on the observer configuration) and calls the subscriber method. It also passes an Varien_Event_Observer method to the subscriber. If the event configuration contains multiple observers they all will be processed in this manner in a loop. Once all the subscribers are executed the function returns control back to the code that fired the event.

Events Available in Magento

Magento offers a number of standard events covering processes of loading, saving, and deleting of models. The names of these events end with:

• _load_before
• _load_after
• _save_before
• _save_after
• _save_commit_after (thrown after a save transaction is committed, after the _save_after event)
• _delete_before
• _delete_after
• _delete_commit_after (thrown after a delete transaction is committed, after the _delete_after event)

Classes extending the abstract model Mage_Core_Model_Abstract have a protected property _eventPrefix which is used to generate event names by combining it with the event name stubs from the list above:

Mage::dispatchEvent($this->_eventPrefix.'_load_after', $this->_getEventData());

For example, the Mage_Sales_Model_Order class’s event prefix is sales_order, so the actual “after loading” event’s name will be sales_order_load_after. Other event names are generated in this manner: catalog_category_load_before, catalog_product_delete_after, customer_save_before, etc.

Not only models but also collections throw events on loading and saving. Collection classes inherit the events functionality from their abstract class Mage_Core_Model_Resource_Db_Collection_Abstract. The event triggering can be found in the protected functions _beforeLoad and _beforeSave, e.g.:

protected function _beforeLoad()
{
    parent::_beforeLoad();
    Mage::dispatchEvent('core_collection_abstract_load_before', array('collection' => $this));
    if ($this->_eventPrefix && $this->_eventObject) {
        Mage::dispatchEvent($this->_eventPrefix.'_load_before', array(
            $this->_eventObject => $this
        ));
    }
    return $this;
}

As you can see, collections also use the _eventPrefix property to generate event names in the children classes.

Besides the standard model events Magento makes use of nearly 400 (!) specific events. You can locate them by searching the codebase for the string Mage::dispatchEvent(. To restrict the number of results, search not the entire code but only the modules you are interested in.

The following Linux command will do the search for you and put the results into a file:

grep -r "Mage::dispatchEvent(" app/code > events.txt

Or you can use this event cheat sheet compiled by Nick Jones

When developing Magento extensions you can define your own events and register observers that catch them. We will look into a few examples in the next post.