Introduction

Tech Note

Current implementation uses a caching library called Stash (, via Stash-bundle). Stash supports the following cache backends: FileSystem, Memcache, APC, Sqlite, Redis and BlackHole.

Use of Memcached (or experimentally using Redis) is a requirement for use in Clustering setup, for overview of clustering feature see Clustering. 

If eZ Publish Platform changes to another cache system, configuration will change in the future, changes to configuration in StashBundle is listed here:

Cache service

The cache system is exposed as a "cache" service, and can be reused by any other service as described on the Persistence cache page.

Configuration

During Setup wizard and manually using ezpublish:configure console command a default configuration is generated currently using FileSystem, using %kernel.cache_dir%/stash to store cache files.

The configuration is placed in ezpublish/config/ezpublish.yml, and looks like:

stash:
    caches:
        default:
            # For eZ Publish Platform versions prior to 5.4/2014.07, use "handlers" instead of "drivers"!
            drivers:
                - FileSystem
            inMemory: false
            registerDoctrineAdapter: false

The default settings used during setup wizard as found in ezpublish/config/ezpublish_setup.yml:

stash:
    caches:
        default:
            # For eZ Publish Platform versions prior to 5.4/2014.07, use "handlers" instead of "drivers"!
            drivers:
                - BlackHole
            inMemory: true
            registerDoctrineAdapter: false

This setting works across all installs and just caches objects within the same request thanks to the inMemory: true setting.

If you want to change to another cache backend, see in Stash backend configuration below for what kind of settings you have available.

Multi repository setup

New in 5.2 is the possibility to select a specific Stash cache pool on a siteaccess or sitegroup level, the following example shows use in a sitegroup:

        ezdemo_group:
            cache_pool_name: "default"
            database:
                ...

The "default" here refers to the name of the cache pool as specified in the stash configuration block shown above, if your install has several repositories (databases), then make sure every group of sites using different repositories also uses a different cache pool to avoid unwanted effects.
NB: We plan to make this more native in the future, so this setting will someday not be needed.

Stash cache backend configuration

General settings

To check which cache settings are available for your installation, run the following command in your terminal :

php ezpublish/console config:dump-reference stash

FileSystem

This cache backend is using local filesystem, by default the Symfony cache folder, as this is per server, it does not support multi server (cluster) setups!

Available settings

path

dirSplit

filePermissions

dirPermissions

memKeyLimit

keyHashFunction

stash:
    caches:
        default:
            # For eZ Publish Platform versions prior to 5.4/2014.07, use "handlers" instead of "drivers"!
            drivers:
                - FileSystem
            inMemory: true
            registerDoctrineAdapter: false
            FileSystem:
                keyHashFunction: 'crc32'

FileSystem cache backend troubleshooting

By default, Stash Filesystem cache backend stores cache to a sub-folder named after the environment (i.e. ezpublish/cache/dev, ezpublish/cache/prod). This can lead to the following issue : if different environments are used for operations, persistence cache (manipulating content, mostly) will be affected and cache can become inconsistent.

To prevent this, there are 2 solutions :

1. Manual

   Always use the same environment, for web, command line, cronjobs...
   
   

2. Share stash cache across Symfony environments (prod / dev)

Either by using another Stash cache backend, or by setting Stash to use a shared cache folder that does not depend on the environment. 
In ezpublish.yml:

stash:
    caches:
        default:
            FileSystem:
                path: "%kernel.root_dir%/cache/common"

This will store stash cache to ezpublish/cache/common.

APC

This cache backend is using shard memory using APC's user cache feature, as this is per server, it does not support multi server (cluster) setups.

Please also note that the default value for apc.shm_size is 128MB. However, 256MB is recommended for APC to work properly. For more details please refer to the APC configuration manual.

Available settings

Memcache

This cache backend is using Memcached, a distributed caching solution, this is the only supported cache solution for multi server (cluster) setups!

✲ All settings but servers are only available with memcached php extension, for more information on these settings and which version of php-memcached they are available in, see: http://php.net/Memcached
✸ If you are on eZ Publish 5.1, make sure to update Stash and StashBundle to get access to these settings.

Example with Memcache

stash:
    caches:
        default:
            # For eZ Publish Platform versions prior to 5.4/2014.07, use "handlers" instead of "drivers"!
            drivers: [ Memcache ]
            inMemory: true
            registerDoctrineAdapter: false
            Memcache:
                prefix_key: ezdemo_
                retry_timeout: 1
                servers:
                    -
                        server: 127.0.0.1
                        port: 11211