Cron System

The cron system in Maho manages scheduled background tasks that run periodically without user intervention. This includes cache cleanup, index updates, email queue processing, and other maintenance operations. The system uses Unix cron expression syntax for scheduling and stores execution history in the database.

Overview

The Maho cron system consists of three main components:

1. Configuration Layer: XML-based job definitions in module config.xml files under crontab/jobs and default/crontab/jobs app/code/core/Mage/Cron/Helper/Data.php22-30 as well as compiled attributes extracted from PHP 8 attributes app/code/core/Mage/Cron/Model/Observer.php83-86
2. Execution Layer: The cron:run CLI command which acts as the entry point, processing scheduled tasks and handling locking. This is handled by the MahoCLI namespace lib/MahoCLI/Commands/CronRun.php24-28
3. Management Layer: CLI commands and an Admin Panel interface for listing, viewing history, and manually running jobs app/code/core/Mage/Cron/controllers/Adminhtml/System/Tools/CronjobsController.php11-13

System Architecture

The following diagram maps the relationship between CLI entry points, the Maho configuration system, and the database persistence layer.

Diagram: Cron System Architecture

Sources: app/code/core/Mage/Cron/Model/Observer.php79-121 app/code/core/Mage/Cron/Helper/Data.php22-30 app/code/core/Mage/Cron/Model/Observer.php83-86 lib/MahoCLI/Commands/CronRun.php48-57

Cron Job Configuration

XML Structure

Cron jobs are traditionally defined in module configuration files. Each job requires a unique identifier and specifies the model method to execute and the schedule.

Element	Description	Code Reference
run/model	Model and method in format class/alias::method	app/code/core/Mage/Cron/Helper/Data.php47
schedule/cron_expr	Direct cron expression (e.g., */5 * * * *)	app/code/core/Mage/Cron/Helper/Data.php41-43
schedule/config_path	Dynamic reference to a system configuration value	app/code/core/Mage/Cron/Helper/Data.php37-40

PHP Attribute Configuration

Maho supports defining cron jobs directly on methods using PHP 8 attributes. While the legacy #[Maho\Config\Observer] can be used to hook into the crontab area app/code/core/Mage/Cron/Model/Observer.php77-78 modern jobs use the compiled attributes indexed into maho_attributes.php. These are accessible via Maho::getCompiledAttributes()['crontab'] app/code/core/Mage/Cron/Model/Observer.php83-86

The Mage_Cron_Helper_Data::getConfiguredJobs method merges both XML-based and attribute-based configurations into a unified array for the system app/code/core/Mage/Cron/Helper/Data.php19-69

Sources: app/code/core/Mage/Cron/Model/Observer.php77-86 app/code/core/Mage/Cron/Helper/Data.php54-66 lib/Maho/Config/Observer.php26-45

System Settings

Global behavior for schedule generation and history cleanup is configured in the system settings via Mage_Cron_Model_Observer constants and config.xml defaults.

Setting	XML Path	Default
Generate Schedules Every	system/cron/schedule_generate_every	15 min app/code/core/Mage/Cron/etc/config.xml44
Schedule Ahead for	system/cron/schedule_ahead_for	60 min app/code/core/Mage/Cron/etc/config.xml45
History Success Lifetime	system/cron/history_success_lifetime	60 min app/code/core/Mage/Cron/etc/config.xml48
History Failure Lifetime	system/cron/history_failure_lifetime	600 min app/code/core/Mage/Cron/etc/config.xml49

Sources: app/code/core/Mage/Cron/Model/Observer.php21-26 app/code/core/Mage/Cron/etc/config.xml41-52

Execution Mechanics

Dispatching Jobs

The Mage_Cron_Model_Observer::dispatch method is the primary engine for processing the cron queue. It performs the following steps:

1. Retrieves pending schedules from the cron_schedule table app/code/core/Mage/Cron/Model/Observer.php80-81
2. Iterates through schedules, checking if the job is enabled via Mage_Cron_Helper_Data::isJobEnabled app/code/core/Mage/Cron/Model/Observer.php87
3. Processes jobs from three sources: Compiled Attributes, XML configuration, and Default XML configuration app/code/core/Mage/Cron/Model/Observer.php94-109
4. Triggers generate() and cleanup() to maintain the schedule queue app/code/core/Mage/Cron/Model/Observer.php117-118

CLI Entry Point

The maho cron:run command lib/MahoCLI/Commands/CronRun.php25 handles execution from the command line. It supports two modes:

• Group Mode: Running maho cron:run default or maho cron:run always dispatches the corresponding event to trigger the observer system lib/MahoCLI/Commands/CronRun.php48-57
• Single Job Mode: Running maho cron:run [job_code] allows executing a specific job immediately. It attempts to lock the job in the cron_schedule table to prevent concurrent runs lib/MahoCLI/Commands/CronRun.php94-103

Data Flow during Execution

The following diagram details the transition from a pending schedule record to a successful execution.

Diagram: Job Execution Sequence

Sources: app/code/core/Mage/Cron/Model/Observer.php79-115 lib/MahoCLI/Commands/CronRun.php48-134 app/code/core/Mage/Cron/Model/Schedule.php1-50

Admin Interface

Maho provides a comprehensive web-based management tool located at System > Tools > Cron Jobs app/code/core/Mage/Cron/controllers/Adminhtml/System/Tools/CronjobsController.php26

Features

• Grid View: Displays all configured jobs, their human-readable schedules (translated via getHumanReadableCronExpr), last run time, and current status app/code/core/Mage/Cron/Helper/Data.php83-132
• Manual Execution: Allows running any job immediately from the browser. The runAction in the controller executes the job and uses fastcgi_finish_request() or flush() to return a response while the job continues in the background app/code/core/Mage/Cron/controllers/Adminhtml/System/Tools/CronjobsController.php123-182
• History Tracking: Provides a detailed execution history for each job code via AJAX, showing duration and error messages app/code/core/Mage/Cron/controllers/Adminhtml/System/Tools/CronjobsController.php77-120
• Status Monitoring: Mage_Cron_Model_Observer::checkCronStatus monitors cron health and displays a warning in the admin header if no jobs have run in the last hour app/code/core/Mage/Cron/Model/Observer.php36-68

Sources: app/code/core/Mage/Cron/controllers/Adminhtml/System/Tools/CronjobsController.php123-182 app/code/core/Mage/Cron/Model/Observer.php36-68 app/code/core/Mage/Cron/Helper/Data.php83-132

Built-in Cron Jobs

Maho includes essential system jobs managed via the Mage_Cron_Model_Observer and other core modules.

Job / Observer	Area	Purpose
cron_observer	crontab	Main dispatcher for default and always schedules app/code/core/Mage/Cron/Model/Observer.php77-128
cron_status_check	adminhtml	Checks if cron is running and alerts admins app/code/core/Mage/Cron/Model/Observer.php35-36
newsletter_send_all	crontab	Processes the newsletter queue.
log_clean	crontab	Cleans up system logs.

Sources: app/code/core/Mage/Cron/Model/Observer.php35-165 app/code/core/Mage/Cron/etc/config.xml41-52