Event System and Observers

The event-observer pattern is Maho's primary mechanism for extending functionality without modifying core code. This system allows modules to listen for and respond to events dispatched throughout the application lifecycle. For information about the module system and configuration, see Module System For class instantiation patterns, see Factory Pattern and Object Instantiation

Event Dispatching Architecture

Events are dispatched through a centralized collection managed by the Mage hub. When an event is triggered, all registered observers for that event are executed in sequence. The Mage::dispatchEvent method is the entry point for triggering these hooks.

The dispatch flow starts from a static call in Mage, which delegates to the application model, and finally to the event collection which iterates through observers registered in the configuration.

Title: "Event Dispatch Flow"

Sources: app/Mage.php83-85 app/Mage.php392-398 app/Mage.php225-228 app/code/core/Mage/Core/Model/App.php196-200

Core Event Methods

Method	Purpose	Location
Mage::dispatchEvent($name, $data)	Dispatch an event with associated data	app/Mage.php392-398
Mage::getEvents()	Retrieve the event collection instance	app/Mage.php225-228

Sources: app/Mage.php225-398

Observer Registration

Observers are primarily registered through module config.xml files or via PHP 8 Attributes. Registration occurs during configuration initialization and is organized by event area (global, frontend, adminhtml, crontab, install).

Title: "Observer Configuration to Code Mapping"

Sources: app/code/core/Mage/Core/Model/Config.php158-162 app/code/core/Mage/Core/Model/Config.php275-280 lib/Maho/Config/Observer.php26-46

Registration Methods

1. XML Registration (Legacy/Standard)

Observers are defined in config.xml under the appropriate area node. The <class> node uses the Maho factory pattern string.

Sources: app/code/core/Mage/Core/Model/Config.php91-98 app/code/core/Mage/CatalogInventory/Model/Observer.php121-122

2. Attribute Registration (Modern)

Maho supports registering observers directly on methods using the #[Maho\Config\Observer] attribute. This requires running composer dump-autoload to compile the registry into vendor/composer/maho_attributes.php.

The attribute allows specifying:

• event: The event name (e.g., catalog_product_save_after).
• area: The scope (global, frontend, adminhtml, crontab, install).
• type: Instantiation type (model for new instance or singleton for shared instance).
• id: Explicit identifier for the observer.
• replaces: The ID of another observer to disable and replace.

Sources: lib/Maho/Config/Observer.php26-46 app/code/core/Mage/CatalogInventory/Model/Observer.php44-45

Event Data Passing

Events carry data through a nested structure where the observer receives a \Maho\Event\Observer object. This object acts as a wrapper around the actual event data.

Title: "Data Flow from Dispatcher to Observer"

Sources: app/Mage.php392-398 app/code/core/Mage/CatalogInventory/Model/Observer.php45-47

Data Access Patterns

Observers use magic getters on the event object to retrieve information.

Pattern	Usage	Example
$observer->getEvent()->getProduct()	Retrieve product model	app/code/core/Mage/CatalogInventory/Model/Observer.php47-49
$observer->getEvent()->getCollection()	Retrieve collection object	app/code/core/Mage/CatalogInventory/Model/Observer.php89-90
$observer->getEvent()->getQuote()	Retrieve quote object	app/code/core/Mage/GiftMessage/Model/Observer.php79-80
$observer->getEvent()->getObject()	Retrieve model being saved/deleted	app/code/core/Maho/AdminActivityLog/Model/Observer.php111-112

Sources: app/code/core/Mage/CatalogInventory/Model/Observer.php47-90 app/code/core/Mage/GiftMessage/Model/Observer.php79-80 app/code/core/Maho/AdminActivityLog/Model/Observer.php111-112

Common Event Patterns

Model Lifecycle Events

Models inheriting from Mage_Core_Model_Abstract automatically dispatch events during save and delete operations.

• model_save_before / model_save_after: Generic events for any model save. Used for audit logging. app/code/core/Maho/AdminActivityLog/Model/Observer.php102-133
• {_eventPrefix}_save_after: Specific events (e.g., catalog_product_save_after or tag_save_after where _eventPrefix is tag). app/code/core/Mage/Tag/Model/Tag.php61-62

Sources: app/code/core/Mage/Tag/Model/Tag.php61-62 app/code/core/Maho/AdminActivityLog/Model/Observer.php102-133

Controller Predispatch Hooks

Commonly used for security checks, session validation, or status monitoring.

• controller_action_predispatch: Triggered before action execution. app/code/core/Mage/Cron/Model/Observer.php35-36
• controller_action_predispatch_{route}_{controller}_{action}: Specific hook for individual actions, used for CAPTCHA verification. app/code/core/Maho/Captcha/Model/Observer.php13-19

Sources: app/code/core/Mage/Cron/Model/Observer.php35-36 app/code/core/Maho/Captcha/Model/Observer.php13-19

Catalog and Inventory Hooks

Maho heavily utilizes observers to decouple catalog operations from inventory and indexing.

• Inventory Updates: catalog_product_save_after triggers Mage_CatalogInventory_Model_Observer::saveInventoryData. app/code/core/Mage/CatalogInventory/Model/Observer.php121-125
• Stock Status: catalog_product_collection_load_after triggers the addition of stock status to collections. app/code/core/Mage/CatalogInventory/Model/Observer.php85-89
• Inventory Loading: catalog_product_load_after adds stock data to individual product models. app/code/core/Mage/CatalogInventory/Model/Observer.php44-47

Sources: app/code/core/Mage/CatalogInventory/Model/Observer.php44-125

Event Areas and Scope

Events are organized by application area to ensure observers only execute in relevant contexts. Areas are defined in the configuration model and loaded selectively.

Area	Scope	Usage Example
global	All requests (Frontend, Admin, CLI)	Default area for many core observers. lib/Maho/Config/Observer.php41
frontend	Customer Storefront	CAPTCHA verification on customer forms. app/code/core/Maho/Captcha/Model/Observer.php13-20
adminhtml	Admin Panel	Admin activity logging and login/logout tracking. app/code/core/Maho/AdminActivityLog/Model/Observer.php48-133
crontab	Background tasks	Cron job dispatching and status monitoring. app/code/core/Mage/Cron/Model/Observer.php77-78
install	Setup process	Installation specific hooks. app/code/core/Mage/Core/Model/Config.php92

Sources: app/code/core/Mage/Core/Model/Config.php89-95 lib/Maho/Config/Observer.php41 app/code/core/Mage/Cron/Model/Observer.php77-81 app/code/core/Maho/AdminActivityLog/Model/Observer.php48-133 app/code/core/Maho/Captcha/Model/Observer.php13-20

Performance and Debugging

Every event dispatch is wrapped in the Maho Profiler, allowing developers to identify slow observers via the profiler key DISPATCH EVENT: {event_name}.

Sources: app/Mage.php394-396