Development Environment Setup

This document provides comprehensive instructions for setting up a local development environment for Maho. It covers system requirements, dependency installation, database configuration, development tooling, and common workflows.

---

System Requirements

PHP Version and Extensions

Maho requires PHP 8.3 or higher. The codebase is actively developed and tested against PHP 8.3, 8.4, and 8.5 composer.json15

Required PHP Extensions: The following extensions must be enabled in your php.ini composer.json16-38:

• ctype, curl, dom, fileinfo, filter, ftp, gd, hash, iconv, intl, json, libxml, mbstring, openssl, pdo, pdo_mysql, session, simplexml, soap, sodium, spl, zip, zlib.

Optional Extensions:

• pdo_pgsql: Required for PostgreSQL database support composer.json95
• pdo_sqlite: Required for SQLite database support composer.json96

Database Engines

Maho supports multiple database engines through Doctrine DBAL 4.4 composer.json43

Engine	Version	Production Use	Notes
MySQL	5.7+	✅ Recommended	Most battle-tested option
MariaDB	10.3+	✅ Recommended	Drop-in MySQL replacement
PostgreSQL	12+	✅ Supported	Modern SQL features
SQLite	3.8+	⚠️ Development only	Single-file database

Composer

Composer 2.x is required for dependency management. The project uses a custom composer plugin mahocommerce/maho-composer-plugin to handle module installations composer.json50

Sources: composer.json15-68 composer.json94-103

---

Development Environment Architecture

Sources: composer.json110-120 lib/Maho.php19-46

---

Initial Setup

1. Clone and Install Dependencies

This installs core dependencies including:

• Frameworks: Symfony components (Console, Mailer, Cache, Validator, HttpClient, Routing) composer.json57-67
• Database: Doctrine DBAL composer.json43
• Images: Intervention Image composer.json46
• Security: Altcha for CAPTCHA composer.json39 WebAuthn composer.json48 and Sodium composer.json35
• Development: PHPStan, PHP-CS-Fixer, Rector, and Pest composer.json84-93

2. File Permissions

The following directories must be writable by the web server and CLI user:

• var/
• media/
• public/media/mahominify/ (for CSS/JS minification) app/code/core/Mage/Core/Helper/Minify.php19

3. Autoloader and Path Resolution

Maho uses a modernized autoloader structure. PSR-4 namespaces are defined for core libraries composer.json110-115 The Maho utility class provides helper methods to interact with the Composer environment:

• Maho::getInstalledPackages(): Returns an array of installed packages via Maho\ComposerPlugin\AutoloadRuntime lib/Maho.php32-35
• Maho::getBasePath(): Resolves the root install path lib/Maho.php40-46
• Maho::getComposerAutoloader(): Returns the Composer\Autoload\ClassLoader instance lib/Maho.php163-169
• Maho::recompilePhpAttributes(): Manually triggers the compilation of PHP attributes (observers, routes) via the Composer plugin runtime lib/Maho.php69-102

4. IDE Support

Maho provides deep IDE integration via the mahocommerce/maho-phpstan-plugin composer.json85 The system includes a baseline configuration to manage existing static analysis issues during development .phpstan.dist.baseline.neon1-25

Sources: composer.json35-93 composer.json110-115 lib/Maho.php19-169

---

Installation Methods

CLI Installation

The maho script provides a robust installation command. For full details on the installation command, see CLI Architecture (10.1) and Installation Command (10.2).

Database Setup

Maho supports multi-database configurations. The database connection details are stored in app/etc/local.xml after installation.

The CLI tool includes specific commands for interacting with the configured database:

• db:connect: Opens the interactive database CLI using credentials from local.xml lib/MahoCLI/Commands/DBConnect.php22-25
• db:query: Executes a one-shot SQL query lib/MahoCLI/Commands/DBQuery.php22-26

Database Query Execution Flow (CLI):

Sources: lib/MahoCLI/Commands/DBQuery.php41-56 lib/MahoCLI/Commands/DBQuery.php58-111 lib/MahoCLI/Commands/DBConnect.php38-43

---

Development Tools Configuration

Code Style (PHP-CS-Fixer)

Maho enforces strict coding standards.

• Ruleset: Uses @PER-CS2.0 with additional project-specific rules composer.json84
• Modernization: Rector is included to automate PHP 8.3+ migrations composer.json89

Static Analysis (PHPStan)

PHPStan is used to find bugs and type mismatches.

• Plugin: Uses mahocommerce/maho-phpstan-plugin for deep integration with Maho's magic methods and factory patterns composer.json85
• Baseline: A comprehensive baseline is maintained in .phpstan.dist.baseline.neon to allow incremental improvements while keeping the build green .phpstan.dist.baseline.neon1-100

Testing (Pest)

Maho uses the Pest testing framework composer.json90 Tests are located in the tests/ directory and use a dedicated runner script tests/pest-with-test-db.php composer.json122-124

Running Tests:

Sources: composer.json122-125 composer.json84-93

---

Modern Development Patterns

Localization and Formatting

The Mage_Core_Model_Locale class handles unit constants and formatting for development app/code/core/Mage/Core/Model/Locale.php13-65

• Defaults: en_US locale, UTC timezone, USD currency app/code/core/Mage/Core/Model/Locale.php18-20
• Unit Support: Includes weight (kg, lb, g) and length (m, cm, in, ft) constants app/code/core/Mage/Core/Model/Locale.php32-48
• Locale Retrieval: Methods like getDefaultLocale() and getLocaleCode() resolve store settings app/code/core/Mage/Core/Model/Locale.php104-114

Configuration and System Settings

System configuration is defined via system.xml files. The core settings include advanced cache controls and rate limiting app/code/core/Mage/Core/etc/system.xml29-77

• Rate Limiting: Limits requests per IP within a specific timeframe app/code/core/Mage/Core/etc/system.xml31-58
• Cache Flushing: Configurable cron expression for automatic cache maintenance app/code/core/Mage/Core/etc/system.xml59-75

Performance Tooling

Maho includes a built-in minification helper Mage_Core_Helper_Minify for frontend assets app/code/core/Mage/Core/Helper/Minify.php17

• Caching: Minified files are stored in public/media/mahominify with filenames based on the source file's modification time app/code/core/Mage/Core/Helper/Minify.php19-194
• Optimization: Uses MatthiasMullie\Minify library for both CSS and JS app/code/core/Mage/Core/Helper/Minify.php14-15

Minification Data Flow:

Sources: app/code/core/Mage/Page/Block/Html/Head.php110-121 app/code/core/Mage/Core/Helper/Minify.php47-100 app/code/core/Mage/Core/Helper/Minify.php134-189 app/code/core/Mage/Core/Model/Locale.php13-65 app/code/core/Mage/Core/etc/system.xml13-150