Caching System

Purpose and Scope

This document describes Maho's multi-layered caching system, which optimizes performance by storing frequently accessed data in memory or on disk. The caching system encompasses configuration caching, layout caching, block output caching, and specialized caches for minified assets and images. It leverages modern PHP 8.3+ features and integrates with Symfony's caching components.

---

Architecture Overview

Maho's caching system reduces database queries and expensive operations by storing computed results. The system supports multiple backend storage engines (via Symfony Cache) and tag-based invalidation for granular cache control.

Cache System Architecture

Sources: app/Mage.php236-245 app/code/core/Mage/Core/etc/config.xml114-120 app/code/core/Mage/Core/Helper/Minify.php19-26 composer.json57

---

Cache Types and Management

Maho categorizes cached data into types, allowing administrators to refresh specific parts of the system without a full flush. These types are defined in app/code/core/Mage/Core/etc/config.xml.

Core Cache Types

Cache Type	Code	Tag	Description
Configuration	config	CONFIG	System and module XML files app/code/core/Mage/Core/etc/config.xml116-120
Layouts	layout	LAYOUT_GENERAL_CACHE_TAG	Layout building instructions app/code/core/Mage/Core/etc/config.xml121-125
Blocks HTML	block_html	BLOCK_HTML	Page blocks HTML output app/code/core/Mage/Core/etc/config.xml126-130
Translations	translate	TRANSLATE	Merged translation files app/code/core/Mage/Core/etc/config.xml131-135
Collections	collections	COLLECTION_DATA	Database collection results app/code/core/Mage/Core/etc/config.xml136-140
Icons	icons	ICONS	SVG icons library app/code/core/Mage/Core/etc/config.xml141-145

Administrative Control

The Mage_Adminhtml_CacheController provides actions to manage these caches via the Admin Panel.

• Flush Storage: flushAllAction() clears the entire cache backend storage using Mage::app()->getCache()->flush() app/code/core/Mage/Adminhtml/controllers/CacheController.php47-53
• Flush System: flushSystemAction() clears all Maho-specific caches and reinitializes configuration. It uses a banning mechanism banUse('config') to prevent reading stale config during the process app/code/core/Mage/Adminhtml/controllers/CacheController.php58-76
• Mass Enable/Disable: massEnableAction() and massDisableAction() toggle cache types in the database app/code/core/Mage/Adminhtml/controllers/CacheController.php81-121
• Minified Files: cleanMinifiedFilesAction() specifically targets the minified CSS/JS storage via the core/minify helper app/code/core/Mage/Adminhtml/controllers/CacheController.php187-204
• Cron Flushing: Maho includes an automated cache flushing mechanism configurable via cron expression system/cache/flush_cron_expr, defaulting to 30 2 * * * app/code/core/Mage/Core/etc/system.xml66-74

Sources: app/code/core/Mage/Adminhtml/controllers/CacheController.php13-205 app/code/core/Mage/Core/etc/config.xml114-146 app/code/core/Mage/Core/etc/system.xml59-75

---

Configuration Caching

The configuration cache is critical for performance, storing the merged XML tree from all active modules and database overrides.

Application Initialization

During bootstrap, Mage_Core_Model_App::init() calls _initCache() to prepare the caching engine before loading the full module configuration app/code/core/Mage/Core/Model/App.php259-260

Cache Save Locking

To prevent race conditions where multiple processes attempt to write the configuration cache simultaneously, Maho employs a locking mechanism:

1. Acquisition: Acquires a named lock Mage::getConfig()->getCacheSaveLock(30, true) before writing app/code/core/Mage/Adminhtml/controllers/CacheController.php62
2. Ban Use: Temporarily bans the use of 'config' cache during reinitialization app/code/core/Mage/Adminhtml/controllers/CacheController.php60
3. Release: Releases the lock after the write operation is complete via releaseCacheSaveLock() app/code/core/Mage/Adminhtml/controllers/CacheController.php71

Sources: app/code/core/Mage/Core/Model_App.php248-272 app/code/core/Mage/Adminhtml/controllers/CacheController.php58-76

---

Asset Minification Caching

Maho includes a specialized caching system for CSS and JavaScript minification via Mage_Core_Helper_Minify.

Processing Logic

When minification is enabled, the system processes assets and stores them in public/media/mahominify/. Mage_Page_Block_Html_Head marks items for minification if they are not in the admin area app/code/core/Mage/Page/Block/Html/Head.php111-121

Minification Flow

Key Features

• Runtime Cache: Uses static arrays $processedCssFiles and $processedJsFiles to avoid re-processing the same file during a single request app/code/core/Mage/Core/Helper/Minify.php25-26
• File Locking: Uses flock() with a .lock file to prevent multiple processes from minifying the same asset simultaneously app/code/core/Mage/Core/Helper/Minify.php155-164
• Validation: Cache is validated by comparing the modification time (filemtime) of the source file against the cached version app/code/core/Mage/Core/Helper/Minify.php206-210

Sources: app/code/core/Mage/Core/Helper/Minify.php17-210 app/code/core/Mage/Page/Block/Html/Head.php111-121

---

Invalidation Strategies and Observers

Maho uses its event-observer system to invalidate caches when data changes. Modern observers are registered via PHP attributes.

Cron Status Caching

Maho caches the last cron status check to avoid expensive database lookups on every admin page load. It uses the crontab tag and a specific key cron_last_status_check app/code/core/Mage/Cron/Model/Observer.php15-17 The check occurs in checkCronStatus app/code/core/Mage/Cron/Model/Observer.php36-68 which is registered as an observer using the #[Maho\Config\Observer] attribute app/code/core/Maho/Config/Observer.php13

Event-Driven Cache Management

Observers react to system changes to update or clear related data:

• Cron Execution: Mage_Cron_Model_Observer uses cache keys to track the last schedule generation and history cleanup times app/code/core/Mage/Cron/Model/Observer.php15-16
• Admin Notifications: The cron status check checkCronStatus is triggered via the controller_action_predispatch event for the adminhtml area app/code/core/Mage/Cron/Model/Observer.php35-36

Data Flow: Admin Cache Management UI

Sources: app/code/core/Mage/Adminhtml/controllers/CacheController.php126-141 app/code/core/Mage/Cron/Model/Observer.php15-68 app/code/core/Mage/Core/etc/config.xml114-146 lib/Maho/Config/Observer.php13