IDE Support and Type Hints

This document describes Maho's developer experience (DX) infrastructure, covering PHPStorm metadata generation, modern PHP type hints, and the Maho Intelligence module. These systems provide accurate code completion, type checking, and AI-assisted development for Maho's dynamic architecture.

For information about static analysis with PHPStan, see Static Analysis and Code Quality. For general development environment setup, see Development Environment Setup.

Purpose and Scope

Maho inherits a string-based factory pattern where models, blocks, and helpers are instantiated using aliases:

Maho provides two primary layers of IDE support to handle this:

1. Static Metadata: .phpstorm.meta.php/ files for traditional IDEs like PHPStorm.
2. Maho Intelligence: A built-in module providing Language Server Protocol (LSP) and Model Context Protocol (MCP) servers for modern editors (VS Code, Zed) and AI assistants.

Sources: app/code/core/Maho/Intelligence/Model/Lsp/Server.php18-27 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php54-78

Maho Intelligence (LSP & MCP)

The Maho_Intelligence module provides deep integration between the Maho runtime and development tools. Unlike static metadata, the LSP server dynamically resolves aliases, XML paths, and event names by inspecting the live configuration.

LSP Server Architecture

The LSP server implements a subset of the Language Server Protocol to provide real-time diagnostics and completions. It uses a React\EventLoop to handle asynchronous JSON-RPC communication.

LSP Message Flow

Sources: app/code/core/Maho/Intelligence/Model/Lsp/Server.php47-84 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php23-37 app/code/core/Maho/Intelligence/Model/Lsp/Handler/Completion.php13-27 app/code/core/Maho/Intelligence/Model/Lsp/DocumentStore.php16-19

Context Detection

The Maho_Intelligence_Model_Lsp_ContextDetector determines what the context the cursor is in to provide relevant suggestions. It supports both PHP and XML files. For XML, it parses tag ancestry to determine alias types (e.g., distinguishing between a model alias in an observer and an FQCN in a model group).

Context	Example Code / XML	Resolution Logic
CONTEXT_MODEL_ALIAS	Mage::getModel('...')	Maps to global/models in config
CONTEXT_CONFIG_PATH	Mage::getStoreConfig('...')	Maps to system.xml paths
CONTEXT_EVENT_NAME	Mage::dispatchEvent('...')	Lists all dispatched events
CONTEXT_XML_METHOD	<action method="...">	Inspects block class methods
CONTEXT_TEMPLATE_PATH	template="..."	Searches theme folders
CONTEXT_FQCN	<class>Mage_Core_Model_Config</class>	Direct class file lookup
CONTEXT_CRON_RUN_MODEL	<model>alias::method</model>	Cron callback resolution

Sources: app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php14-22 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php25-37 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php54-78 app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php107-130

XML Structure Indexing

To support completion in XML files, the module uses Maho_Intelligence_Model_Lsp_XmlStructureIndex. This class merges all module XML files (config.xml, system.xml, adminhtml.xml) and theme layout files to build a map of valid parent-child relationships.

XML Structure Discovery

Sources: app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php14-22 app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php23-33 app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php68-80 app/code/core/Maho/Intelligence/Model/Lsp/XmlStructureIndex.php160-175

PHPStorm Metadata System

For PHPStorm users, the .phpstorm.meta.php/ directory contains mapping files that bridge the gap between string aliases and concrete PHP classes.

Metadata File Structure

File	Purpose	Target Method
models.meta.php	Model factory mappings	Mage::getModel(0)
blocks.meta.php	Block factory mappings	Mage_Core_Model_Layout::createBlock(0)
resource_models.meta.php	Resource model mappings	Mage::getResourceModel(0)

Type Hints and Modernization

Maho leverages modern PHP features (8.3+) to improve type safety and IDE discoverability. This includes strict typing for method parameters and return values.

PHP 8.3 Attributes and Types

Maho uses explicit return types and property types to reduce ambiguity.

app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php41-44:

Variable Type Hints

In areas where types are dynamic (like observers), PHPDoc @var hints or explicit class names in signatures are used to ensure the IDE understands the object context.

app/code/core/Maho/Intelligence/Model/Lsp/Handler/Completion.php19-27:

The #[Override] attribute is also used to clearly indicate overridden methods, improving code readability and maintainability.

Sources: app/code/core/Maho/Intelligence/Model/Lsp/ContextDetector.php41-44 app/code/core/Maho/Intelligence/Model/Lsp/Handler/Completion.php19-27

Real-time Diagnostics

The Maho_Intelligence_Model_Lsp_Handler_Diagnostic class scans document text for unresolved class aliases in both PHP and XML.

• PHP Scanning: Uses regex patterns to find aliases within factory calls like Mage::getModel(), Mage::helper(), ->createBlock(), and Mage::getResourceModel().
• XML Scanning: Validates aliases found in tags like <class>, <source_model>, <backend_model>, <render>, <renderer>, <frontend_model>, and type="..." attributes. It also checks cron job model::method patterns.
• Resolution: Validates aliases via the Maho_Intelligence_Model_Registry and reports warnings for unresolved aliases.

Sources: app/code/core/Maho/Intelligence/Model/Lsp/Handler/Diagnostic.php23-39 app/code/core/Maho/Intelligence/Model/Lsp/Handler/Diagnostic.php73-102 app/code/core/Maho/Intelligence/Model/Lsp/Handler/Diagnostic.php104-151

CLI Database Support

Maho provides CLI commands that bridge the gap between application configuration and external tools. Commands like db:connect and db:query allow developers to interact with the database using credentials from local.xml without manual configuration in an IDE.

Database CLI Flow

Troubleshooting IDE Support

Issue	Potential Cause	Solution
No completion for Mage::getModel()	Missing metadata or LSP server not running	Check .phpstorm.meta.php/ or ensure Maho_Intelligence is active.
XML tags showing as errors	Missing XSD or LSP context	Use Maho Intelligence LSP for context-aware XML validation.
Diagnostics not updating	LSP Debounce	The LSP server uses a 0.3s debounce for diagnostics. app/code/core/Maho/Intelligence/Model/Lsp/Server.php29
Stale XML suggestions	Index not updated	The index is invalidated on didSave for module XML files. app/code/core/Maho/Intelligence/Model/Lsp/Server.php185-191

Sources: app/code/core/Maho/Intelligence/Model/Lsp/Server.php29 app/code/core/Maho/Intelligence/Model/Lsp/Server.php185-191