Event Observers and Hooks

The event observer system provides a publish-subscribe mechanism that enables loose coupling between modules. Events are dispatched at key points in the application lifecycle, allowing modules to react to system actions without modifying core code. This system is fundamental to Maho's extensibility architecture.

For information about the factory pattern and object instantiation, see Factory Pattern and Object Instantiation For module structure and configuration, see Module System

Event Dispatching Mechanism

Events are dispatched using the static method Mage::dispatchEvent($name, array $data = []) app/Mage.php2184-2190 When an event is dispatched, all registered observers for that event are executed in sequence with access to the event data.

The dispatch method is defined in app/Mage.php. The method performs profiling around the actual dispatch to track performance app/Mage.php2185-2189

Event Dispatch Flow

This diagram bridges the natural language "Event Dispatch" to the code entities involved in the execution chain.

Sources: app/Mage.php2184-2190 app/code/core/Mage/Core/Model/App.php418-422

Observer Registration

Maho supports two primary methods for registering observers: traditional XML configuration and modern PHP Attributes.

1. PHP Attributes (Recommended)

Maho introduces the #[Maho\Config\Observer] attribute lib/Maho/Config/Observer.php26-28 This allows developers to declare observers directly on the method that handles the event. This is compiled into a high-performance registry during composer dump-autoload into vendor/composer/maho_attributes.php lib/Maho/Config/Observer.php20-21

The attribute supports the following parameters lib/Maho/Config/Observer.php39-45:

• event: The event name to observe (e.g., catalog_product_save_after).
• area: Scope (e.g., global, frontend, adminhtml, crontab, install) lib/Maho/Config/Observer.php31
• type: Instantiation type (model for a new instance per dispatch or singleton for a shared instance) lib/Maho/Config/Observer.php32
• id: Unique identifier for the observer.
• replaces: The id of another observer to disable and replace, supporting class names or aliases lib/Maho/Config/Observer.php34-37

Example Implementation:

Sources: lib/Maho/Config/Observer.php13-46 app/code/core/Mage/Cron/Model/Observer.php35-37

2. XML Configuration

Observers can still be registered in module config.xml files under area-specific event nodes. These are merged by the configuration model during initialization app/code/core/Mage/Core/Model/Config.php274-280

From Configuration to Runtime Registry

This diagram maps configuration sources to the internal PHP structures that manage event execution.

Sources: app/code/core/Mage/Core/Model/App.php196-200 lib/Maho/Config/Observer.php20-22

Observer Class Implementation

Observer classes contain methods that respond to events. Each observer method receives a \Maho\Event\Observer object containing the event data.

Observer Method Signature

Sources: app/code/core/Maho/Captcha/Model/Observer.php20-21 app/code/core/Mage/Cron/Model/Observer.php36-37

Common Core Observers

Observer Class	Event Name	Purpose
Maho_Captcha_Model_Observer	controller_action_predispatch_*	Verifies CAPTCHA tokens on various frontend and admin forms app/code/core/Maho/Captcha/Model/Observer.php13-21
Mage_Cron_Model_Observer	controller_action_predispatch	Checks cron status and warns admin users if not running app/code/core/Mage/Cron/Model/Observer.php35-71
Mage_Cron_Model_Observer	default (crontab area)	Processes the cron queue and schedules tasks app/code/core/Mage/Cron/Model/Observer.php77-119
Mage_Wishlist_Model_Observer	checkout_cart_update_items_before	Moves quote items to wishlist during cart updates app/code/core/Mage/Wishlist/Model/Observer.php35-37
Mage_Log_Model_Visitor	controller_action_predispatch	Initializes visitor information from server data app/code/core/Mage/Log/Model/Visitor.php217-219

Sources: app/code/core/Maho/Captcha/Model/Observer.php13-21 app/code/core/Mage/Cron/Model/Observer.php35-71 app/code/core/Mage/Cron/Model/Observer.php77-119 app/code/core/Mage/Wishlist/Model/Observer.php35-37 app/code/core/Mage/Log/Model/Visitor.php217-219

The encryption_key_regenerated Pattern

The encryption_key_regenerated event is a specialized pattern where multiple modules coordinate to re-encrypt data when the system encryption key is rotated via the encryption:key:regenerate CLI command.

Data Re-encryption Flow

The regeneration command triggers the event and passes encrypt_callback and decrypt_callback closures so observers can process data using both keys during the transition. This ensures that sensitive data remains decryptable after the key change.

Sources: app/Mage.php2184-2190

Best Practices

1. Area Specificity: Register observers in the most specific area possible (frontend, adminhtml, crontab, install) to reduce execution overhead for unrelated requests lib/Maho/Config/Observer.php31
2. Exception Handling: Wrap observer logic in try-catch blocks where appropriate to prevent a failure in one observer from breaking critical application flows app/code/core/Mage/Cron/Model/Observer.php110-114
3. Use Singletons: For observers that maintain state during a request, use type: 'singleton' to avoid redundant object instantiation lib/Maho/Config/Observer.php32
4. Attribute Compilation: Always run composer dump-autoload after adding, modifying, or removing a #[Maho\Config\Observer] attribute to update the compiled registry lib/Maho/Config/Observer.php21

Sources: lib/Maho/Config/Observer.php21-32 app/code/core/Mage/Cron/Model/Observer.php110-114