Cache-block #

This page is for designers who make expensive parts of a template cheap. A {cache-block} stores the output of its body and reuses it until its keys change or it expires. Implementation: lib/eztemplate/classes/eztemplatecachefunction.php and eztemplatecacheblock.php.

Contents #

1. Syntax and parameters
2. Keys
3. Expiry
4. Safe patterns
5. Mistakes
6. Settings and clearing

Syntax and parameters #

{cache-block keys=array( $module_result.uri, $current_user.role_id_list|implode( ',' ) ) expiry=3600}
    ...
{/cache-block}

Without keys, the block's position in the template is the only key: one copy for every page and visitor.

Keys #

Every value that changes the output must be in the keys:

subtree_expiry also implies ignore_content_expiry: such a block expires only for publishes below its node. The simple design keys its whole frame by URI, basket state and user id; the admin pagelayout builds a user hash from role and limitation lists.

Expiry #

• Default: two hours, and on every content publish.
• A footer that never changes with content: ignore_content_expiry and a long expiry.
• A menu of a section: subtree_expiry with the section's root node, so publishing elsewhere keeps it.

Safe patterns #

{* a top menu: same for everyone with the same roles on the same page *}
{cache-block keys=array( $module_result.uri, $current_user.role_id_list|implode( ',' ) ) subtree_expiry=2}
    {include uri='design:pagelayout/menu.tpl'}
{/cache-block}

{* a footer: same everywhere, changes rarely *}
{cache-block ignore_content_expiry expiry=86400}
    {include uri='design:pagelayout/footer.tpl'}
{/cache-block}

Mistakes #

• User data without the user in the keys: one visitor's name shown to others.
• csp_nonce() inside a block: the stored nonce is wrong for every later request, and the script is blocked.
• A fetch inside the block whose result is used outside it: on a cache hit, the fetch does not run.
• Keys with many distinct values (full query strings, timestamps): one file per value, and no reuse. Cast or reduce them (the admin pagelayout casts its section filter to a number for this reason).
• Nested cache-blocks: work, but make invalidation hard to reason about; avoid them.

Settings and clearing #

• site.ini [TemplateSettings] TemplateCache=enabled turns cache-blocks on (disabled: never used).
• DelayedCacheBlockCleanup (default disabled) keeps expired subtree blocks on disk for a cronjob to remove.
• Clear: php bin/php/ezcache.php --clear-id=template-block.

Related pages #

• Caching for designers
• Run-once
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.