Glossary

This glossary provides detailed definitions for codebase-specific terms, jargon, and domain concepts essential for onboarding engineers working with the Maho e-commerce platform. The entries cover architectural patterns, legacy migrations, core systems, utilities, frontend, backend, testing, and CLI commands with references to key files and lines to enable deep technical understanding.

---

Core System Concepts

Mage

The primary static class serving as the core application hub in Maho. It provides global registry storage, factory methods for models, helpers, singleton instances, and access to configuration and app lifecycle.

• Implementation: Singleton static class defined in app/Mage.php app/Mage.php18-558
• Key methods:
  • Mage::run(): Bootstraps and starts the application lifecycle app/Mage.php544-558
  • Mage::app(): Returns the main application instance (Mage_Core_Model_App) app/Mage.php287-299
  • Mage::getModel($name): Factory method resolving model names to class and instantiating app/Mage.php408-412
  • Mage::getSingleton($name): Returns shared singleton instances app/Mage.php422-426
  • Mage::helper($name): Instantiates helper objects app/Mage.php436-440
  • Mage::registry() / Mage::register(): Global registry storage for shared data app/Mage.php147-181

The Mage class maintains static registries and caches. It manages the application root directory and integrates event dispatching and configuration access.

Maho Namespace

Maho modernizes and reorganizes much of the platform’s codebase under the Maho\ PHP namespace for core libraries and utilities, while CLI tooling resides in MahoCLI\. This namespace migration from old namespaces like Varien_ improves code clarity and autoloading.

• Implementation detail: In app/bootstrap.php, many legacy Varien_ class names are aliased via class_alias to their Maho\ counterparts to maintain backward compatibility app/bootstrap.php29-101
• Core libraries and system components are implemented under Maho\ (e.g. Maho\DataObject replacing Varien_Object) lib/MahoCLI/Commands/HealthCheck.php56-106

Factory Pattern

Maho employs a factory pattern extensively to instantiate models, helpers, and blocks via factory methods resolving logical aliases to concrete classes. This enables reusability, modularity, and runtime class rewrites for overrides.

• Entry points: Mage::getModel(), Mage::getSingleton(), and Mage::helper()
• Class resolution: Controlled by configuration in Mage_Core_Model_Config which reads module XML and rewrite declarations app/code/core/Mage/Core/Model/Config.php114-125
• Rewrites: Local or community modules can override core classes by specifying class rewrites in XML configuration.

This pattern abstracts class instantiation and supports flexible extension without modifying core files.

Varien

The legacy namespace and base classes inherited originally from Magento and OpenMage.

• Primary base class: Varien_Object, a data object with magic getter/setter, event dispatching capabilities, now mostly replaced by Maho\DataObject app/code/core/Mage/Core/Model/Locale.php13
• Data cache: Mage::objects() returns a Maho\DataObject\Cache instance, used for caching objects in memory during request lifecycle app/Mage.php236-245

Legacy Varien classes remain with aliases to maintain compatibility but core development is aligned under the Maho namespace.

Sources: app/Mage.php18-558 app/bootstrap.php29-101 lib/MahoCLI/Commands/HealthCheck.php56-106 app/code/core/Mage/Core/Model/Config.php114-125 app/code/core/Mage/Core/Model/Locale.php13

---

Data & Persistence

EAV (Entity-Attribute-Value)

An extensible data model allowing entities to have variable attribute sets. Instead of fixed columns, attributes are stored as separate rows associated with an entity, enabling dynamic attributes (e.g., Products, Customers).

• Core modules: Implemented primarily in the Mage_Eav module app/code/core/Mage/Core/Model/Config.php17
• Attribute metadata and entity relationships are stored and accessed through EAV models.

Flat Catalog

A performance optimization where the flexible, normalized EAV data is flattened into denormalized tables for faster frontend reads and listing operations.

• Modules involved: Mage_Catalog, Mage_Index modules handle flat table synchronization app/code/core/Mage/Core/Model/Config.php27-31
• Flat tables are periodically rebuilt through indexers for frontend consumption.

Indexers

Background processes that transform and aggregate raw data (EAV or otherwise) into optimized forms such as flat tables, price indices, or search indices to improve frontend query performance.

• Location: Core indexer base classes and configuration reside in Mage_Index app/code/core/Mage/Core/Model/Config.php27
• Triggering: Indexers listen to events and data changes, e.g., Mage_Index_Model_Indexer::processEntityAction() recomputes indices app/code/core/Mage/Tag/Model/Tag.php85-89

Sources: app/code/core/Mage/Core/Model/Config.php17-31 app/code/core/Mage/Tag/Model/Tag.php85-89

---

Frontend & Layout

Layout Handles

Strings used as keys for specific page types or states to select corresponding layout XML instructions that define block hierarchies and templates.

• Example handles: default, catalog_product_view
• Managed by: Mage_Core_Model_Layout_Update which loads and merges XML updates for active handles app/code/core/Mage/Core/Model/Layout.php20

Blocks

PHP objects representing UI logic that prepare data for templates (.phtml files) and can contain child blocks. Blocks are the core view units rendering page components.

• Base class: Mage_Core_Block_Abstract
• Creation: Blocks are instantiated through the layout’s _generateBlock() method app/code/core/Mage/Core/Model/Layout.php211-226
• Blocks expose methods for rendering, caching, and child management.

WYSIWYG Directives

Special embedded tokens or tags supported in the WYSIWYG editor (TipTap integration) to dynamically inject content such as media URLs, variables, or store configuration during rendering.

• These directives are parsed and replaced at runtime in content rendering pipelines.

Deferred Image Resize

A performance optimization where product images are stored in original sizes upon upload, and resized images are generated lazily on first request using the Intervention Image library.

• Reduces upload storage and delays CPU-intensive image processing until necessary.

Sources: app/code/core/Mage/Core/Model/Layout.php20-226

---

Architecture & Logic

Store Scopes

Maho supports hierarchical configuration scopes comprising Global > Website > Store > Store View referring to environment segmentation and configuration visibility.

• Access: Mage::getStoreConfig($path, $store) loads config per store context app/Mage.php277-280

Observers

Event listeners executing application logic on system events to enable modular extensions.

• Dispatching: Mage::dispatchEvent($name, array $data) fires events, calling registered observers app/Mage.php455-459
• PHP Attributes: Modern approach using PHP attributes like #[Maho\Config\Observer] registers observers declaratively in PHP classes, compiled into maho_attributes.php app/code/core/Mage/CatalogInventory/Model/Observer.php44

This replaces legacy XML-based event configuration for improved clarity and performance.

mahoFetch

A modern JavaScript helper library replacing Prototype.js AJAX calls in admin UI. It provides promise-based fetch functionality for asynchronous admin interactions.

ACL (Access Control List)

Security subsystem restricting access to admin UI menu items and actions based on roles.

• Enforced in layouts by acl attributes in XML removing blocks or menu items dynamically app/code/core/Mage/Core/Model/Layout.php157-160

LSP and MCP Servers

Components of the Maho Intelligence module providing IDE and AI assistant integration.

• LSP (Language Server Protocol): Provides editor features like autocomplete, diagnostics, and goto definition for PHP and XML files. Started using CLI command dev:lsp:start maho96
• MCP (Model Context Protocol): Provides context and completions tailored for AI assistants. Started using dev:mcp:start
• Detection: Maho_Intelligence_Model_Lsp_ContextDetector detects contexts in code files for request routing app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php1

Config Sections

Top-level nodes in system config XML (system.xml) defining grouped configuration fields (e.g., adminhtml, stores).

• Used for configuration caching granularity app/code/core/Mage/Core/Model/Config.php89-95

---

System Mapping Diagrams

HTTP Request Flow to Controller Action

This diagram maps a natural language URL request through the Mage bootstrap and front controller dispatch to the actual controller action and layout blocks responsible for rendering.

Developer Intent to Code Intelligence Context Mapping

Maps developer natural language intents to the internal context detector and code entities used by the LSP and MCP for autocompletion and navigation in IDE/AI tooling.

Sources: app/Mage.php71-558 app/code/core/Mage/Core/Model/Layout.php13-226 app/code/core/Mage/CatalogInventory/Model/Observer.php44 lib/Maho.php19-197 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php1

---

Testing and API Glossary

MahoApiTestCase

Base PHP unit test class for API integration tests. It sets up environment for JSON-RPC API calls ensuring isolation and repeatability.

• Found under tests/ directory (not explicitly in current extract)

JsonRpcClient

PHP client class used in tests to perform JSON-RPC calls against the Maho API backend.

• Works with MahoApiTestCase to test API endpoints.

dev:module:list

CLI command listing all registered modules with their versions and status.

• Implemented in lib/MahoCLI/Commands/DevModuleList.php and registered in maho script maho95-96

---

CLI Command Glossary

The Maho CLI (maho script) provides maintenance, development, and administrative commands for managing the application and data maho1-106

Command	Purpose	Implementation Reference
cache:flush	Clear all cache backends	MahoCLI\Commands\CacheFlush maho36
db:connect	Open an interactive database console	MahoCLI\Commands\DBConnect maho44
db:query	Run arbitrary SQL queries	MahoCLI\Commands\DBQuery maho45
health-check	Analyze legacy files and resource issues	MahoCLI\Commands\HealthCheck maho69
serve	Start local PHP development server	MahoCLI\Commands\Serve maho77
shell	Start interactive PHP REPL	MahoCLI\Commands\Shell maho78
dev:lsp:start	Start Language Server Protocol server for IDE integration	MahoCLI\Commands\DevModuleList maho95-96
dev:mcp:start	Start Model Context Protocol server for AI assistants	registered similarly, see maho maho95-96

The CLI is built using Symfony Console components, auto-discovers commands, and defines a wide range of operational utilities.

---

This completes the comprehensive glossary of Maho platform-specific terms, architectural patterns, APIs, and development tools.

Sources:
app/Mage.php18-558 app/bootstrap.php29-101 lib/MahoCLI/Commands/HealthCheck.php56-106
app/code/core/Mage/Core/Model/Config.php14-125 app/code/core/Mage/Core/Model/Layout.php13-226
lib/Maho.php19-197 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php1 maho1-106