Template caches #

A template is cached in several ways at once, each with its own key, its own expiry and its own way to clear it. Knowing which cache holds an output is most of the work when "my change does not show". This page lists them in the order a request meets them.

Contents #

1. Overview
2. Compiled templates
3. The template override cache and the design base cache
4. The content view cache
5. The template-block cache (cache-block)
6. The INI cache
7. Clearing, and what a deploy clears
8. Related pages

Overview #

The caches the kernel knows are listed in eZCache::fetchList() (kernel/classes/ezcache.php); each has an id for php bin/php/ezcache.php --clear-id=<id> and tags for --clear-tag=<tag>:

php bin/php/ezcache.php --list-ids and --list-tags print the full list of an installation, with the caches of extensions. The template-related settings on the site siteaccess:

TemplateCompile:  {ezini( 'TemplateSettings', 'TemplateCompile' )}
DevelopmentMode:  {ezini( 'TemplateSettings', 'DevelopmentMode' )}
TemplateCache:    {ezini( 'TemplateSettings', 'TemplateCache' )}
NodeTreeCaching:  {ezini( 'TemplateSettings', 'NodeTreeCaching' )}
ViewCaching:      {ezini( 'ContentSettings', 'ViewCaching' )}
CachedViewModes:  {ezini( 'ContentSettings', 'CachedViewModes' )}

Output:

TemplateCompile:  enabled
DevelopmentMode:  disabled
TemplateCache:    enabled
NodeTreeCaching:  disabled
ViewCaching:      enabled
CachedViewModes:  full;sitemap;pdf;googlesitemap

Compiled templates #

The PHP files of the template compiler, one per template, siteaccess and locale. A compiled template is rebuilt when its own file is newer; an included template is only checked for a newer file with DevelopmentMode=enabled. Clear with --clear-id=template.

The template override cache and the design base cache #

The design resource keeps two lookups:

• the override cache (override/): the match rules of override.ini per template, built by eZTemplateDesignResource::createOverrideCache(). A new override rule or a new template file is not seen until it is cleared (--clear-id=template-override); a changed existing template is.
• the design base cache: the ordered list of design folders of the siteaccess, written when DesignLocationCache=enabled (eZTemplateDesignResource::allDesignBases()). Clear it (--clear-id=design_base) after adding a design to an extension or enabling an extension with a design.

The content view cache #

content/view stores the whole $Result of a node view (HTML, content_info, the persistent variable, the list of templates used) for the view modes in [ContentSettings] CachedViewModes (full;sitemap;pdf;googlesitemap on a development installation). The cache file name is a hash of (eZNodeviewfunctions::generateViewCacheFile()):

• node ID, view mode, language, offset, layout;
• the user's role IDs, limited-assignment values and discount rules (each can be left out with a ViewCacheTweaks value: ignore_userroles, ignore_userlimitedlist, ignore_discountlist);
• the index file, the siteaccess (unless ignore_siteaccess_name) and, for URI siteaccesses, the access type;
• the view parameters (unless ignore_viewparameters);
• user preferences listed in CachedViewPreferences for the view mode;
• keys an extension adds through the content/view/cachekeys event filter.

It expires when content is published (the cache manager clears the node and the nodes related to it, by the rules of viewcache.ini), when the global content-view-cache expiry timestamp moves, and when one of the templates in template_list is newer than the cache file. A node template can shorten its life with {set-block scope=root variable=cache_ttl}0{/set-block} (as the cjw_newsletter templates do): $cache_ttl set to 0 stops caching of that page, a positive value is a lifetime in seconds. Clear with --clear-id=content.

The template-block cache (cache-block) #

cache-block stores the output of a part of a template (lib/eztemplate/classes/eztemplatecachefunction.php, eztemplatecacheblock.php). Not run on a development installation: rendering a cache-block writes a cache file, so this example is shown without output:

{cache-block keys=array( $node.node_id, $view_parameters.offset ) subtree_expiry=$node.node_id expiry=3600}
    {foreach fetch( 'content', 'list', hash( 'parent_node_id', $node.node_id, 'limit', 10 ) ) as $child}
        {node_view_gui content_node=$child view='line'}
    {/foreach}
{/cache-block}

How the cache is found:

• The key always includes the placement of the tag (eZTemplateCacheBlock::placementString(): start line and column, end line and column, template file) and the siteaccess name, plus the keys value when given. Two cache-blocks never share a file, and moving a cache-block in its template makes a new file.
• The file name is the md5 of that key, stored in template-block/<a>/<b>/<c>/<md5>.cache, or below the subtree folder of the node for subtree_expiry.
• Without ignore_content_expiry, every publish expires every such block: publishing sets the template-block-cache timestamp (eZContentObject::expireTemplateBlockCache()). The global global-template-block-cache timestamp, moved by clearing the cache, expires all blocks.
• With TemplateCache=disabled the block's content is rendered every time, as if the tag were not there.

Things that follow:

• Anything that differs per visitor, per role or per request inside a block must be in keys, or it is shown to the next visitor too. $current_user.contentobject_id in the keys makes one block per user.
• rand, currentdate and similar values freeze until the block expires.
• A def inside a block is not run on a cache hit: variables the rest of the template needs must be defined outside.

The designer's guide is Cache block.

The INI cache #

Settings files are cached as PHP in var/cache/ini (global_ini) and the site cache's ini folder. A change to an .ini file of an extension or of settings/ is seen after --clear-tag=ini; the templates that read settings with ezini() then get the new value.

Clearing, and what a deploy clears #

php bin/php/ezcache.php --clear-id=template,template-override --allow-root-user
php bin/php/ezcache.php --clear-tag=template --allow-root-user
php bin/php/ezcache.php --clear-all --allow-root-user

./console exp:velocity deploy (kernel/classes/expvelocitydeploy.php) clears, in this order: the template, template-override, translation and design_base caches, then, after reloading PHP and restarting Velocity, content, exphttpcache, ezjscore-packer (with --packer) and template-block. The order matters: a page rendered with the old code between a clear and a reload would be cached again.

Which to clear after what:

Related pages #

• The template compiler
• Template compilation and cache
• Cache block
• Template resources and overrides
• Caching in applications
• ezcache
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.