PHPackages                             silvertree/m2-maintenance-cache-backend - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. silvertree/m2-maintenance-cache-backend

ActiveMagento2-module[Caching](/categories/caching)

silvertree/m2-maintenance-cache-backend
=======================================

Cache-based maintenance mode system that uses Redis/cache backends instead of filesystem checks

1.0.2(9mo ago)5711↓21.4%1Apache-2.0PHPPHP >=8.2

Since Jul 26Pushed 9mo agoCompare

[ Source](https://github.com/silvertree-brands/m2-maintenance-cache-backend)[ Packagist](https://packagist.org/packages/silvertree/m2-maintenance-cache-backend)[ RSS](/packages/silvertree-m2-maintenance-cache-backend/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (1)Versions (3)Used By (0)

Maintenance Cache Backend Module
================================

[](#maintenance-cache-backend-module)

**Module:** `Silvertree_MaintenanceCacheBackend`
**Version:** 1.0.1 **Compatibility:** Magento 2.4+ / PHP 8.2+

Overview
--------

[](#overview)

This module replaces Magento's filesystem-based maintenance mode with a configurable cache backend system, provides better scalability for distributed environments.

Key Features
------------

[](#key-features)

- **Persistent Maintenance Mode**: Survives `cache:flush` and `cache:clean` operations
- **Multiple Backend Support**: Redis, File, Memcached, or any Magento-supported cache backend
- **IP Whitelist Support**: Full compatibility with Magento's IP whitelist feature
- **Graceful Fallback**: Automatically falls back to filesystem when cache is unavailable
- **Zero Breaking Changes**: Maintains full compatibility with existing maintenance commands
- **Performance Optimized**: Dedicated cache backend

Installation
------------

[](#installation)

1. **Install the module:**

    ```
    composer require silvertree/m2-maintenance-cache-backend
    php bin/magento module:enable Silvertree_MaintenanceCacheBackend
    php bin/magento setup:upgrade
    ```
2. **Configure cache backend** (see the Configuration section below)
3. **Test the configuration:**

    ```
    php bin/magento maintenance:enable
    php bin/magento maintenance:status
    php bin/magento cache:flush
    php bin/magento maintenance:status  # Should still show enabled
    php bin/magento maintenance:disable
    ```

Configuration
-------------

[](#configuration)

Add a `cache/maintenance` section to your `app/etc/env.php` file. When not configured, the module gracefully falls back to Magento's default filesystem behavior.

### Redis Backend (Recommended)

[](#redis-backend-recommended)

```
'cache' => [
    'maintenance' => [
        'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis',
        'backend_options' => [
            'server' => '127.0.0.1',
            'database' => '14',
            'port' => '6379',
            'password' => '',
            'timeout' => '2.5',
            'compression_threshold' => '2048',
            'compression_library' => 'gzip',
            'automatic_cleaning_factor' => 0
        ]
    ]
]
```

### Memcached Backend Example (untested).

[](#memcached-backend-example-untested)

```
'cache' => [
    'maintenance' => [
        'backend' => 'Magento\\Framework\\Cache\\Backend\\Memcached',
        'backend_options' => [
            'servers' => [
                [
                    'host' => 'localhost',
                    'port' => 11211,
                    'weight' => 1
                ]
            ],
            'compression' => true,
            'compatibility' => false
        ]
    ]
]
```

Usage
-----

[](#usage)

The module works transparently with all existing Magento maintenance commands:

```
# Enable maintenance mode
php bin/magento maintenance:enable

# Enable with IP whitelist
php bin/magento maintenance:enable --ip=192.168.1.1 --ip=10.0.0.1

# Check status
php bin/magento maintenance:status

# Allow additional IPs
php bin/magento maintenance:allow-ips 192.168.1.100

# Disable maintenance mode
php bin/magento maintenance:disable
```

Architecture
------------

[](#architecture)

### Plugin System

[](#plugin-system)

The module uses Magento's plugin system to intercept `MaintenanceMode` operations:

- `aroundIsOn()`: Checks cache for maintenance status and IP whitelist
- `aroundSet()`: Sets maintenance status in cache
- `aroundSetAddresses()`: Manages IP whitelist in cache

### Cache Key Structure

[](#cache-key-structure)

- **Maintenance Status**: `MAINTENANCE_MODE_STATUS`
- **IP Addresses**: `MAINTENANCE_MODE_ADDRESSES`

### Fallback Behavior

[](#fallback-behavior)

When cache is unavailable or not configured:

1. Service operations return `false` or empty arrays
2. Plugin methods call `$proceed()` to use original filesystem logic
3. System continues operating with filesystem-based maintenance mode
4. No exceptions thrown - graceful degradation

Performance Considerations
--------------------------

[](#performance-considerations)

### Redis Configuration

[](#redis-configuration)

- **Dedicated Database**: Use a separate Redis database (14) to avoid conflicts
- **Persistence**: Configure Redis persistence to survive server restarts
- **Memory**: Maintenance data is minimal (~100 bytes per status)
- **Compression**: Enable compression for larger IP whitelists

### File Backend

[](#file-backend)

- **Directory Permissions**: Ensure the web server has read/write access
- **Disk Space**: File backend uses minimal disk space
- **Performance**: Slower than Redis but suitable for single-server deployments

Troubleshooting
---------------

[](#troubleshooting)

### Maintenance Mode Not Persisting

[](#maintenance-mode-not-persisting)

**Problem**: Maintenance mode is disabled after `cache:flush`

**Solutions**:

1. Verify `cache/maintenance` configuration in `app/etc/env.php`
2. Check Redis connectivity and database configuration
3. Review system logs for cache backend errors
4. Test cache backend with: `php bin/magento cache:status`

### IP Whitelist Not Working

[](#ip-whitelist-not-working)

**Problem**: IP addresses are not properly whitelisted

**Solutions**:

1. Verify IP addresses are correctly stored: `php bin/magento maintenance:status`
2. Check cache backend connectivity
3. Review plugin logs for IP comparison issues
4. Test with filesystem fallback by removing cache configuration

### Cache Backend Errors

[](#cache-backend-errors)

**Problem**: Cache backend connection failures

**Solutions**:

1. Check Redis/Memcached service status
2. Verify connection parameters (host, port, password)
3. Review system logs for specific error messages
4. Test connection manually with tools like `redis-cli`

### Performance Issues

[](#performance-issues)

**Problem**: Slow maintenance mode operations

**Solutions**:

1. Use Redis backend for better performance
2. Optimize cache backend configuration
3. Enable compression for large IP whitelists
4. Monitor cache backend performance metrics

Development
-----------

[](#development)

### Custom Cache Backends

[](#custom-cache-backends)

To implement a custom cache backend:

1. Extend `Magento\Framework\Cache\Backend\AbstractBackend`
2. Configure in `cache/maintenance/backend`
3. Ensure compatibility with cache frontend interface
4. Test fallback behavior when backend fails

License
-------

[](#license)

[Open Source License](LICENSE)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance58

Moderate activity, may be stable

Popularity24

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~9 days

Total

2

Last Release

278d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5f04480bd8951e0c1f02a8c5369df5508ffc3ea9b2e9dd613839867dd9cf55ba?d=identicon)[rootindex](/maintainers/rootindex)

---

Top Contributors

[![rootindex](https://avatars.githubusercontent.com/u/505211?v=4)](https://github.com/rootindex "rootindex (6 commits)")

### Embed Badge

![Health badge](/badges/silvertree-m2-maintenance-cache-backend/health.svg)

```
[![Health](https://phpackages.com/badges/silvertree-m2-maintenance-cache-backend/health.svg)](https://phpackages.com/packages/silvertree-m2-maintenance-cache-backend)
```

###  Alternatives

[lizardmedia/module-varnish-warmer

Varnish Cache Warmer Magento2 module by Lizard Media

6276.8k](/packages/lizardmedia-module-varnish-warmer)[vendic/module-optimize-cache-size

Magento 2 extension that reduces the number of cache keys by removing catalog\_product\_view\_id\_, catalog\_product\_view\_sku\_, catalog\_product\_view\_attribute\_set\_, catalog\_category\_view\_id\_ layout handles by default

3453.6k](/packages/vendic-module-optimize-cache-size)[litespeed/module-litemage

LiteMage Full Page Cache for LiteSpeed Web Server

3254.8k](/packages/litespeed-module-litemage)[redchamps/module-easy-cache-clean

Clean invalidated cache(s) easily in a Magento 2 store

2838.0k](/packages/redchamps-module-easy-cache-clean)[yireo/magento2-autoflushcache

2813.5k](/packages/yireo-magento2-autoflushcache)[graycore/magento2-graph-ql-cache

A Magento 2 module that modifies the built-in GraphQlCache FPC.

121.5k](/packages/graycore-magento2-graph-ql-cache)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)