Module System

Purpose and Scope

The Module System is Maho's architectural pattern for organizing functionality into self-contained, reusable components. This document covers module structure, declaration, dependency resolution, and integration with the configuration system.

Maho maintains compatibility with the legacy Magento 1 module structure while modernizing the platform through PHP 8.3+ standards and streamlined core logic app/code/core/Mage/Core/Model/Config.php7-11

---

Overview

Modules in Maho are self-contained packages that extend the platform's functionality. Each module encapsulates related business logic, including models, blocks, controllers, helpers, and configuration. The module system provides:

• Namespace organization: Modules follow the Namespace_Module naming convention (e.g., Mage_Core app/code/core/Mage/Core/Model/Config.php16 Maho_AdminActivityLog app/code/core/Maho/AdminActivityLog/Model/Observer.php12).
• Code isolation: Each module resides in its own directory within defined code pools or Composer packages.
• Dependency management: Explicit declaration of module dependencies in XML or Composer to determine load order.
• Configuration merging: Automatic merging of module config.xml into the global configuration tree app/code/core/Mage/Core/Model/Config.php274-280
• Activation control: Modules can be globally enabled or disabled via declaration files or system configuration app/code/core/Mage/Core/etc/system.xml86-94

---

Module Structure

Each module follows a standardized directory structure within its code pool location:

Key Configuration Files:

File	Purpose	Required
config.xml	Defines models, blocks, helpers, events, and routes.	Yes
system.xml	Defines configuration fields for the Admin System > Configuration section.	No

Sources: app/code/core/Mage/Core/Model/Config.php274-280 app/code/core/Mage/Core/Model/Config.php89-95

---

Module Declaration and Discovery

Modules are activated via XML declaration files located in app/etc/modules/. These files define the module's presence to the configuration object during initialization.

Hardcoded Core Modules

Maho maintains an internal hardcoded list of core modules to ensure consistent loading order for base components and critical platform functionality app/code/core/Mage/Core/Model/Config.php15-71

Composer Integration

Modern Maho modules are managed via Composer. The Maho utility class provides methods to interact with installed packages:

• Maho::getInstalledPackages(): Returns an array of Maho packages installed via Composer lib/Maho.php32-35
• Maho::findFile(): Resolves absolute paths for files within installed packages, respecting overrides lib/Maho.php134-146

Discovery Sequence

Title: Module Configuration Initialization Flow

Sources: app/Mage.php126-137 app/code/core/Mage/Core/Model/Config.php272-280 lib/Maho.php32-35

---

Code Pools and Overrides

Maho uses code pools and the Composer autoloader to organize source code and allow for overrides.

Pool	Location	Usage
core	app/code/core/	Reserved for Maho core modules (Mage_* and Maho_*).
local	app/code/local/	Used for site-specific customizations and legacy overrides.
community	app/code/community/	Legacy pool for third-party extensions.

Composer Autoloader

Maho integrates deeply with the Composer ClassLoader lib/Maho.php163-169 During development, the system can update the autoloader dynamically to reflect new files or class map changes lib/Maho.php174-195

Sources: app/Mage.php253-256 lib/Maho.php163-169 lib/Maho.php174-195

---

Module Components and Factories

Maho uses a factory pattern to instantiate module classes based on configuration aliases defined in config.xml.

Class Alias Resolution

Title: Factory Pattern Class Resolution

Namespace Modernization

Maho is transitioning from legacy Varien_ namespaces to modern Maho\ namespaces. This is reflected in the Composer autoload configuration composer.json110-115

Sources: app/code/core/Mage/Core/etc/config.xml20-24 composer.json110-115

---

Modern Attribute-Based Configuration

Maho introduces a modernized way to declare module functionality using PHP 8.3 attributes. This reduces reliance on XML and allows for a more developer-friendly experience.

Compiled Attributes

To maintain high performance, attributes are compiled into a PHP file at vendor/composer/maho_attributes.php lib/Maho.php51-58 This file is generated via the Maho::recompilePhpAttributes() method, which triggers the AttributeCompiler lib/Maho.php69-102

Observer Registration

Observers can be registered directly on class methods using the #[Maho\Config\Observer] attribute.

• Mage_CatalogInventory_Model_Observer::addInventoryData observes catalog_product_load_after app/code/core/Mage/CatalogInventory_Model_Observer.php44-45
• Maho_AdminActivityLog_Model_Observer::logAdminLogin observes admin_user_authenticate_after app/code/core/Maho/AdminActivityLog/Model/Observer.php48-49

Cron Job Registration

Cron jobs are also defined via attributes (e.g., #[Maho\Config\CronJob]), moving away from the <crontab> section in config.xml.

Sources: lib/Maho.php51-58 lib/Maho.php69-102 app/code/core/Mage/CatalogInventory/Model/Observer.php44-46

---

Activation and Deactivation

Modules can be enabled or disabled through two primary mechanisms:

1. Declaration Files: Setting <active>false</active> in app/etc/modules/Namespace_Module.xml.
2. Admin Configuration: Output from specific modules can be disabled in the Admin Panel under System > Configuration > Advanced > Advanced > Disable Modules Output app/code/core/Mage/Core/etc/system.xml86-94

Cache Management

Module configuration is heavily cached. The CONFIG cache type stores the merged config.xml and local.xml trees app/code/core/Mage/Core/etc/config.xml116-120 When modules are added or updated, this cache must be refreshed via the Admin or CLI.

Sources: app/code/core/Mage/Core/etc/system.xml86-94 app/code/core/Mage/Core/etc/config.xml116-120

---

Technical Reference: Module Metadata

Module Configuration Node (config.xml)

Title: Configuration Node Hierarchy

Sources: app/code/core/Mage/Core/Model/Config.php89-95