Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Move Filesystem troubleshooting to FileSystem section, and change terminology from handler to driver

...

Current implementation uses a caching library called Stash, via Stash-bundle. If this changes, then the configuration format will most likely change as well. Stash supports the following cache handlersdrivers: FileSystemMemcache, APC, Sqlite, XCache and BlackHole.

...

Code Block
titleDefault ezpublish.yml
stash:
    caches:
        default:
            # With the version of Stash bundled with eZ Publish Platform 5.1 and 5.2 this is called "handlers:"!
            drivers:
                - FileSystem
            inMemory: false
            registerDoctrineAdapter: false

...

Code Block
titleezpublish_setup.yml
stash:
    caches:
        default:
            # With the version of Stash bundled with eZ Publish Platform 5.1 and 5.2 this is called "handlers:"!
            drivers:
                - BlackHole
            inMemory: true
            registerDoctrineAdapter: false

...

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

Note
titleNote for "inMemory" cache with long running scripts

Use of inMemory caching with BlackHole or any other cache handler driver should not be used for long running scripts as it will over time return stale data, inMemory cache is not shared across requests/processes, so invalidation does not happen!

...

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

...

drivers configuration

General settings

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

Code Block
languagebash
php ezpublish/console config:dump-reference stash

FileSystem

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

...

Info
titleIssues with Microsoft Windows

If you are using a Windows OS, you may encounter an issue regarding long paths for cache directory name. The paths are long because Stash uses md5 to generate unique key that are sanitized really quickly.

Solution is to change the hash algorithm used by Stash.

Code Block
titleSpecifying key hash function
stash:
    caches:
        default:
            # With the version of Stash bundled with eZ Publish Platform 5.1 and 5.2 this is called "handlers:"!
            drivers:
                - FileSystem
            inMemory: true
            registerDoctrineAdapter: false
            FileSystem:
                keyHashFunction: 'crc32'

This configuration is only recommended for Windows users.

Note: You can also define the path where you want the cache files to be generated.
Note2: This configuration is only recommended for Windows users, but does solve this problem. 

 

FileSystem driver troubleshooting

By default, Stash Filesystem driver stores cache to a sub-folder named after the environment (i.e. ezpublish/cache/devezpublish/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 environments

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

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

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

APC

This cache handler driver is using shard memory using APC's user cache feature, as this is per server, it does not support multi server (cluster) setups, unless you use PHP-FPM on a dedicated server (this way, user cache can be shared among all the workers in one pool).

...

ttlThe time to live of the cache in seconds, default set to 500 (8.3 minutes)
namespaceA namespace to prefix cache keys with to avoid key conflicts with other eZ Publish sites on same eZ Publish installation, default is null.

Memcache

This cache handler driver 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 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.

 

Info

When using Memcache handlerdriver, it's strongly recommended to also use inMemory cache (see example below).
This will help reducing network traffic between your webserver and your Memcached server, unless you have very long running cli processes which then might end up acting on stale data.

...

Code Block
stash:
    caches:
        default:
            # With the version of Stash bundled with eZ Publish Platform 5.1 and 5.2 this is called "handlers:"!
            drivers: [ Memcache ]
            inMemory: true
            registerDoctrineAdapter: false
            Memcache:
                prefix_key: ezdemo_
                retry_timeout: 1
                servers:
                    -
                        server: 127.0.0.1
                        port: 11211
Warning
titleConnection errors issue

If memcached does display connection errors when using the default (ascii) protocol, switching to binary protocol (in the stash configuration and memcached daemon) should resolve the issue.

Troubleshootings

By default, Stash 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 :

...

Share stash cache across environments

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

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

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