Factory Pattern and Object Instantiation

Purpose and Scope

This page explains Maho's factory pattern implementation and object instantiation mechanisms. It covers how the Mage static class provides factory methods for creating models, helpers, blocks, and other objects using grouped class names (aliases), how singletons are managed through the registry pattern, and how the configuration system enables class rewrites for customization.

For information about the configuration system that powers class resolution, see Configuration System. For details on the module system that registers classes, see Module System. For block-specific instantiation patterns, see Layout System.

Factory Pattern Overview

Maho implements a centralized factory pattern through the Mage static class, which serves as the primary entry point for object instantiation throughout the application app/Mage.php18-19 Instead of directly instantiating classes with new, developers use factory methods that resolve grouped class names to actual class names through the configuration system app/Mage.php401-414

Title: Object Instantiation Flow

Sources: app/Mage.php18-92 app/Mage.php401-414 app/Mage.php426-433 app/Mage.php510-517

Grouped Class Names (Aliases)

Maho uses a two-part naming convention called "grouped class names" or "aliases" to reference classes. The format is module_group/class_suffix, where:

• module_group is typically the lowercase module name (e.g., catalog, core, customer).
• class_suffix identifies the specific class within that module's namespace.

Alias Pattern	Resolves To	Example
module/class	Mage_Module_Model_Class	catalog/product → Mage_Catalog_Model_Product
module/sub_class	Mage_Module_Model_Sub_Class	catalog/product_option → Mage_Catalog_Model_Product_Option
module (helper)	Mage_Module_Helper_Data	catalog → Mage_Catalog_Helper_Data
module/helper	Mage_Module_Helper_Helper	catalog/image → Mage_Catalog_Helper_Image

The configuration system maps these aliases to actual class names, allowing for class rewrites and maintaining flexibility. This mapping is extensively used in the configuration model to resolve paths like core/config to Mage_Core_Model_Config app/code/core/Mage/Core/Model/Config.php237-238 The configuration model maintains $_classNameCache and $_blockClassNameCache to speed up subsequent resolutions app/code/core/Mage/Core/Model/Config.php112-123

Sources: app/code/core/Mage/Core/Model/Config.php112-125 app/code/core/Mage/Core/Model/Config.php234-240

Model Instantiation

The Mage::getModel() method creates new instances of model classes app/Mage.php401-414 Each call returns a fresh object instance, making it suitable for entity operations where multiple objects are needed, such as loading multiple stock items in an observer app/code/core/Mage/CatalogInventory/Model/Observer.php51

Title: Model Creation Sequence

The method signature allows passing constructor arguments to initialize the object state immediately upon creation app/Mage.php401-414

Sources: app/Mage.php401-414 app/code/core/Mage/Core/Model/Config.php112-117 app/code/core/Mage/CatalogInventory/Model/Observer.php51

Singleton Pattern and Registry

The Mage::getSingleton() method implements the singleton pattern by storing instances in an internal registry app/Mage.php426-433 The same instance is returned for subsequent calls with the same alias, which is essential for stateful objects like sessions or indexers app/code/core/Mage/Tag/Model/Tag.php85-89

Title: Singleton Registry Logic

The registry is a simple associative array stored in Mage::$_registry app/Mage.php57 Values can be explicitly registered using Mage::register() app/Mage.php147-156 and retrieved via Mage::registry() app/Mage.php179-182

Sources: app/Mage.php57 app/Mage.php147-156 app/Mage.php426-433 app/code/core/Mage/Tag/Model/Tag.php85-89

Helper Instantiation

Helpers are utility classes instantiated as singletons through Mage::helper() app/Mage.php510-517 They are stateless by convention and often handle translations or common data formatting tasks, such as escaping HTML app/code/core/Mage/Core/Helper/Abstract.php180-203

When only the module name is provided (e.g., Mage::helper('core')), it defaults to the Data helper class within that module's Helper namespace (Mage_Core_Helper_Data) app/Mage.php510-517

Sources: app/Mage.php510-517 app/code/core/Mage/Core/Helper/Abstract.php180-203

Resource Model Instantiation

Resource models handle database operations and are retrieved using Mage::getResourceModel() app/Mage.php436-449 They are mapped in the configuration under the models section but within a resourceModel sub-node. The Mage_Core_Model_Config::getResourceModel() method is the internal driver for this resolution app/code/core/Mage/Core/Model/Config.php234-240

Title: Model vs Resource Model Resolution

Sources: app/Mage.php436-449 app/code/core/Mage/Core/Model/Config.php234-240

Block Instantiation

Blocks are typically instantiated through the layout system app/code/core/Mage/Core/Model/Layout.php223 The layout system uses grouped class names similar to models but resolves them against the blocks configuration node. The configuration model caches block class names in $_blockClassNameCache app/code/core/Mage/Core/Model/Config.php123 Blocks also have access to a factory instance for internal object creation app/code/core/Mage/Core/Block/Abstract.php172-177

Sources: app/code/core/Mage/Core/Model/Config.php119-123 app/code/core/Mage/Core/Block/Abstract.php172-177 app/code/core/Mage/Core/Block/Abstract.php224-227 app/code/core/Mage/Core/Model/Layout.php223

Modern Observer Instantiation

Maho introduces a modern way to register observers using PHP 8 attributes. The #[Maho\Config\Observer] attribute can specify the instantiation type as either model (new instance per dispatch) or singleton (shared instance). This replaces the traditional XML-based observer registration and allows for better IDE support and static analysis.

Example from Mage_CatalogInventory:

Sources: app/code/core/Mage/CatalogInventory/Model/Observer.php44-45 app/code/core/Mage/Tag/Model/Tag.php194-196 app/code/core/Maho/AdminActivityLog/Model/Observer.php48-49 app/code/core/Mage/GiftMessage/Model/Observer.php20-21

Factory Method Summary

Method	Purpose	Returns	Caching
Mage::getModel()	Create model instance	New instance	No
Mage::getSingleton()	Get model singleton	Singleton	Yes (registry)
Mage::helper()	Get helper singleton	Singleton	Yes (registry)
Mage::getResourceModel()	Create resource model instance	New instance	No
Mage::getResourceSingleton()	Get resource model singleton	Singleton	Yes (registry)
Mage::objects()	Access internal object cache	Maho\DataObject\Cache	Yes (static) app/Mage.php236-245

Sources: app/Mage.php236-245 app/Mage.php401-536