Custom CLI Commands

Purpose and Scope

This page explains how to create custom CLI commands for Maho by extending BaseMahoCommand. It covers the Symfony Console integration, the automatic discovery mechanism, and common implementation patterns for interacting with the Maho core. For built-in command reference, see Command-Line Interface.

CLI System Architecture

Maho's CLI system is built on Symfony Console. The entry point is the maho script in the root directory, which initializes a Symfony Application and registers commands from multiple sources.

CLI Command Registration Flow

The registration process combines explicit instantiation for core commands and dynamic discovery for extensions and local overrides.

Registration and Discovery Flow

Sources: maho1-106 lib/MahoCLI/CommandDiscoverer.php22-64

Base Class Hierarchy

Custom commands must extend BaseMahoCommand to inherit Maho initialization logic and utility methods.

Sources: lib/MahoCLI/Commands/BaseMahoCommand.php18-35 lib/MahoCLI/Commands/CronRun.php28 lib/MahoCLI/Commands/FrontendLayoutDebug.php33 lib/MahoCLI/Commands/TranslationsMissing.php28

BaseMahoCommand Class

BaseMahoCommand is the abstract foundation for all Maho CLI tools lib/MahoCLI/Commands/BaseMahoCommand.php18

Core Methods

Method	Description	Implementation Detail
initMaho()	Boots the Maho environment	Sets isSecureArea to true and initializes the application with the admin store scope lib/MahoCLI/Commands/BaseMahoCommand.php20-24
humanReadableSize()	Formats byte counts	Uses logarithmic calculation to return strings like "1.5 MB" or "2 GB" lib/MahoCLI/Commands/BaseMahoCommand.php26-34

Sources: lib/MahoCLI/Commands/BaseMahoCommand.php18-35

Scaffolding a New Command

Maho includes a developer tool to generate command skeletons.

Using dev:create-command

Run php bin/maho dev:create-command to generate a new command class lib/MahoCLI/Commands/CreateCommand.php23

1. Input: The command prompts for a name (e.g., module:sync) and description lib/MahoCLI/Commands/CreateCommand.php34-58
2. Logic: It converts the colon-separated name into a PascalCase class name (e.g., ModuleSyncCommand) lib/MahoCLI/Commands/CreateCommand.php105-108
3. Output: Creates a new PHP file in lib/MahoCLI/Commands/ with the #[AsCommand] attribute and execute() method boilerplate lib/MahoCLI/Commands/CreateCommand.php110-150

Sources: lib/MahoCLI/Commands/CreateCommand.php22-151

Command Discovery Mechanism

The CommandDiscoverer class handles dynamic registration lib/MahoCLI/CommandDiscoverer.php17

1. Scanning: It recursively iterates through lib/MahoCLI/Commands within specified base directories lib/MahoCLI/CommandDiscoverer.php31-38
2. Filtering: It skips the base class BaseMahoCommand.php and ignores the core vendor/mahocommerce/maho path during general discovery to avoid duplicate registration lib/MahoCLI/CommandDiscoverer.php48-54
3. Validation: It ensures discovered classes are subclasses of Symfony's Command before instantiation lib/MahoCLI/CommandDiscoverer.php57-60

Sources: lib/MahoCLI/CommandDiscoverer.php22-64 maho100-104

Common Implementation Patterns

Initializing the Application

Always call $this->initMaho() at the start of execute() if your command needs to interact with Models, Collections, or Configuration lib/MahoCLI/Commands/BaseMahoCommand.php20-24

Interactive User Input

Use Symfony's QuestionHelper for interactive prompts.

Sources: lib/MahoCLI/Commands/AdminUserChangepassword.php34-38

Tabular Output

Use the Table helper for displaying structured data like cron jobs or log statuses.

Sources: lib/MahoCLI/Commands/CronList.php32-46 lib/MahoCLI/Commands/LogStatus.php32-82

Running Cron Jobs Manually

The cron:run command demonstrates how to manually trigger observers associated with the crontab event area lib/MahoCLI/Commands/CronRun.php54-56 It also shows how to lock a job using Mage_Cron_Model_Schedule::tryLockJob() to prevent concurrent execution lib/MahoCLI/Commands/CronRun.php95-98

Sources: lib/MahoCLI/Commands/CronRun.php41-134

Return Codes

Follow standard Symfony Console return codes:

• Command::SUCCESS (0): Execution completed without errors lib/MahoCLI/Commands/AdminUserChangepassword.php64
• Command::FAILURE (1): Logic error or resource not found lib/MahoCLI/Commands/AdminUserChangepassword.php57
• Command::INVALID (2): Input validation failed lib/MahoCLI/Commands/AdminUserChangepassword.php42

Sources: lib/MahoCLI/Commands/AdminUserChangepassword.php42-64