Overview

Maho is an open-source e-commerce platform forked from OpenMage/Magento 1, modernized for PHP 8.3+ with current dependencies. This page provides a high-level introduction to Maho's architecture, core systems, and design philosophy.

What is Maho?

Maho descends from Magento 1 → OpenMage, preserving the proven architectural patterns while replacing legacy dependencies with modern standards. It is designed as a drop-in replacement for Magento 1 projects with a complete toolchain.

Modernization Strategy:

• PHP 8.3+ Requirement: Leveraging modern syntax, strict types, and PHP attributes for system configuration composer.json15 README.md24
• Symfony Components: Replaces legacy Zend Framework components with symfony/console, symfony/mailer, symfony/validator, symfony/cache, symfony/http-client, symfony/routing, and symfony/filesystem composer.json57-67 README.md26
• Doctrine DBAL 4: Modern database abstraction supporting MySQL, MariaDB, PostgreSQL, and SQLite composer.json43 README.md25
• Enhanced Security: Built-in support for Passkeys (WebAuthn), 2FA, and Altcha anti-spam composer.json39-48 README.md36
• Modern Image Handling: Integration of Intervention Image 4.0 for advanced manipulation and deferred resizing composer.json46
• Vanilla JavaScript: Removal of jQuery and Prototype.js in favor of 100% vanilla JS README.md28-29

Current Version: 26.5.0 app/Mage.php120

Sources: README.md1-48 composer.json1-137 app/Mage.php118-121

---

Architectural Patterns

MVC with XML Configuration Maho follows a strict Model-View-Controller pattern where controllers route HTTP requests, models implement business logic, and blocks/templates render the UI. Configuration is centralized in XML files merged from modules, database, and environment variables.

Module-Based Organization Functionality is organized into self-contained modules:

• app/code/core/Mage/*: Inherited core modules (e.g., Mage_Core, Mage_Eav, Mage_Catalog, Mage_Sales) app/code/core/Mage/Core/Model/Config.php15-71
• app/code/core/Maho/*: New Maho-specific features (Blog, Giftcard, FeedManager, Intelligence, AdminActivityLog) app/code/core/Maho/AdminActivityLog/Model/Observer.php13
• app/code/local/*: Project-specific overrides and extensions.

Static Facade Pattern The Mage class app/Mage.php18 acts as the primary service locator and framework hub.

Attribute-Based Extensibility In addition to traditional XML-based observers, Maho supports PHP attributes for registering event listeners and cron jobs. These are compiled into an optimized map via the Maho\ComposerPlugin\AttributeCompiler lib/Maho.php83 These compiled artifacts are stored in vendor/composer/maho_attributes.php lib/Maho.php51-58

Sources: app/Mage.php18-137 app/code/core/Mage/Core/Model/Config.php13-73 lib/Maho.php49-83 app/code/core/Maho/AdminActivityLog/Model/Observer.php13

---

Entry Points

Entry Points and Request Flow

Application Entry Points

Entry Point	File	Initializer	Purpose
Web	public/index.php	Mage::run()	HTTP requests for storefront and admin panel app/Mage.php58-61
CLI	bin/maho	Mage::app()	Symfony Console-based tasks composer.json58
Utility	lib/Maho.php	Maho::getComposerAutoloader()	Low-level system utilities and autoloader management lib/Maho.php163-169

Sources: app/Mage.php58-121 lib/Maho.php1-169 composer.json58

---

Bootstrap and Configuration

Bootstrap Stages

1. Root Establishment: Mage::setRoot() establishes the application's absolute path app/Mage.php190-208
2. Configuration Initialization: Mage_Core_Model_Config::init() app/code/core/Mage/Core/Model/Config.php272-280 aggregates configuration from:
   • Base Files: app/etc/config.xml and app/etc/local.xml.
   • Module Files: etc/config.xml from all active modules app/code/core/Mage/Core/Model/Config.php15-71
   • Compiled Attributes: Observers and cron jobs registered via PHP attributes lib/Maho.php51-58
   • Database: The core_config_data table app/code/core/Mage/Core/etc/config.xml40-42
3. App Initialization: Mage::app() or Mage::run() sets up the environment, cache, and current store scope.

Configuration Caching The system uses the CONFIG tag for configuration caching app/code/core/Mage/Core/Model/Config.php73 To optimize performance, specific sections like adminhtml, crontab, install, stores, and websites can be cached separately app/code/core/Mage/Core/Model/Config.php89-95

Sources: app/Mage.php190-208 app/code/core/Mage/Core/Model/Config.php15-280 app/code/core/Mage/Core/etc/config.xml40-120

---

Core System Components

The Mage Facade

Key Framework Classes

Class	Role
Mage	Static hub for factories and application state app/Mage.php18
Mage_Core_Model_Config	Handles XML merging, class alias resolution, and module loading app/code/core/Mage/Core/Model/Config.php13-14
Maho	Utility class for package management, maintenance mode, and autoloader updates lib/Maho.php19
Mage_Core_Model_App_Area	Manages different application areas like frontend and adminhtml app/code/core/Mage/Core/Model/App/Area.php13

Modern Frontend Features Maho introduces advanced frontend performance features like Deferred JavaScript and Load on Intent app/locale/en_US/Mage_Core.csv5 The Mage_Page_Block_Html_Head block manages asset minification and sorting app/code/core/Mage/Page/Block/Html/Head.php111-121

Sources: app/Mage.php18-92 app/code/core/Mage/Core/Model/Config.php13-280 lib/Maho.php19-212 app/code/core/Mage/Page/Block/Html/Head.php111-121 app/locale/en_US/Mage_Core.csv5