DocumentationCommerceConfiguration Guide

[On Premises]{class="badge informative" title="Applies to Adobe Commerce on-premises projects only."}

Cache backend options and storage reference

Last update: September 15, 2026

CREATED FOR:

  • Intermediate
  • Admin
  • Developer
NOTE
This page documents on-premises app/etc/env.php configuration.
For Adobe Commerce on Cloud projects, the ece-tools package generates the resulting app/etc/env.php configuration during deployment based on the deploy variable configuration in .magento.env.yaml. You do not edit the env.php file. See Best Practices for Valkey and Redis Service Configuration and Deploy variables.

The Commerce application uses a low-level cache frontend and backend to provide access to cache storage. Commerce supports several caching backends and strategies, each suited to different use cases. This page describes the available backends and how they differ.

NOTE
Varnish handles full-page caching at the HTTP level for on-premises deployments. The Fastly service handles it for Cloud deployments. Neither solution uses the low-level cache backend.

Backend cache options

The following table summarizes the available backend caches:

Backend
Description
Configuration guide
File system
Default. Stores cache data in files under var/cache/. No configuration required.
N/A
Redis
In-memory data store for high-performance caching.
Use Redis for default cache
Valkey
Open-source, Redis-compatible alternative.
Use Valkey for default cache
Database
Custom cache engine backed by a database
Create custom cache engines (Adobe Developer documentation)
IMPORTANT
Redis cache is not supported for Adobe Commerce 2.4.9, or patch releases later than 2.4.5-p16, 2.4.6-p14, 2.4.7-p9, and 2.4.8-p4. If you are upgrading to one of these versions, configure Valkey and update the cache configuration to use it. For Adobe Commerce on-premises, see set up Valkey.

Cache backend and L2 implementations implementation-approaches

Commerce supports direct cache backends and L2 caching. A direct backend selects cache storage. L2 caching adds a local cache layer in front of remote storage.

Direct cache backends

The following table summarizes cache backend configuration values for <Commerce-install-dir>/app/etc/env.php. It does not enable L2 caching.

Commerce version
Backend
Configuration value
2.4.8 and earlier, where supported
file
Default. No configuration required
2.4.8 and earlier, where supported
Redis
Magento\Framework\Cache\Backend\Redis
2.4.8 and earlier, where supported
Valkey
Magento\Framework\Cache\Backend\Valkey
2.4.9 and later, plus supported backports
file
file
2.4.9 and later, plus supported backports
Valkey
valkey

For exact patch-level support, see the System Requirements.

[!TAB Zend-based cache (2.4.8 and earlier)]

Backend examples

For on-premises deployments, the following examples configure direct cache backends in <Commerce-install-dir>/app/etc/env.php. They do not enable L2 caching. Do not use these examples for Adobe Commerce on Cloud deployments, which use the ece-tools package to generate the resulting app/etc/env.php configuration during deployment.

Redis

Use the full Redis class name only on releases where Redis is supported:

code language-php?start_inline=1 
'cache' => [
    'frontend' => [
        'default' => [
            'backend' => 'Magento\\Framework\\Cache\\Backend\\Redis',
            'backend_options' => [
                'server' => '127.0.0.1',
                'database' => '0',
                'port' => '6379',
            ],
        ],
    ],
],
Valkey
code language-php?start_inline=1 
'cache' => [
    'frontend' => [
        'default' => [
            'backend' => 'valkey',
            'backend_options' => [
                'server' => '127.0.0.1',
                'database' => '0',
                'port' => '6379',
            ],
        ],
    ],
],

L2 caching

L2 (two-level) caching adds a local cache layer on each web node in front of shared remote cache storage, reducing network traffic between Commerce and the remote cache. For implementation options, version support, and configuration steps, see L2 cache configuration.

For Cloud projects, configure L2 caching through the deployment variables described in Deploy variables.

recommendation-more-help
commerce-operations-help-configuration