{cache} · PAD tags

Syntax

{cache 'name'} ... {/cache}
{cache 'name', ttl=300, vary=$value} ... {/cache}
{anytag cache=3600, vary=$value} ... {/anytag}

Parameters

name: The section's name - its key within the application, and what padFragmentForget ( 'name' ) drops.

Options

ttl: The seconds the rendering is kept, 300 when not given.
vary: Whatever else the rendering depends on: vary=$userId keeps a copy per user, vary=$country one per country.

Description

{cache 'name', ttl=300} ... {/cache} renders its content once and keeps the result; for the next ttl seconds every request gets the stored rendering and nothing inside the section runs - no tag, no query, no remote fetch. It is for the parts of a page that cost more than the rest: a list of best sellers, a menu built from the database, a report over a year of orders. The PHP of the page runs before the template, so it runs on a hit too; put the expensive work in the template, inside the section.

The name is the section's key within the application. vary= adds whatever else the rendering depends on - a user id, a country, a page number - and keeps one copy per value. When what the section shows has changed, padFragmentForget ( 'name' ) drops it at once (with a vary value as its second argument to drop one copy), and padFragmentForget () drops them all.

The cache=<seconds> option does the same for any tag: {topProducts cache=3600}...{/topProducts} is keyed on the page, the tag as written and its evaluated parameters, and skips the tag's own handler on a hit. Closing pipes and end options run on a stored rendering as on a fresh one. What the section leaves for the rest of the page is kept with it and made again on a hit: its {push}es, and the booking of a paged tag for a {pager} further down.

Otherwise a section keeps its text, not its effects: what it sets, stores or defines - a {set}, {increment}, a {data}, {content} or {bool} store, a {define} or {macro}, the totals of a callback= - happens on the miss only, and on a hit the page goes on with the variables and stores this request has. Put such a tag before the section, or in a {nocache} part, which renders every time.

Some renderings are never stored: one that holds the visitor's CSRF token (a {form}, {csrf}, a live region) or the request's {nonce}, and a request for one response fragment or the post of a live region. $padFragmentCache chooses the store - 'file' (the default, under DATA/cache/fragments/), 'apcu', or FALSE to render every time. A {cache} without a name, or without its closing tag, is a strict error.

Examples

A named section

The squares are computed on the first request and served from the cache for the next ten minutes.

Templateexamples/cache/1-section.pad

{cache 'cacheSquares', ttl=600}
  <p>{sequence '1..8', name='n'}{$n | * @}{notLast@n}, {/notLast@n}{/sequence}</p>
{/cache}

Resultopen alone

1, 4, 9, 16, 25, 36, 49, 64

A copy per visitor, and the option form

vary= keeps one rendering per user; cache= on any tag caches that tag the same way.

Templateexamples/cache/2-vary.src

{cache 'basket', ttl=60, vary=$userId}
  {basket}<li>{$product}: {$quantity}</li>{/basket}
{/cache}

{topProducts cache=3600, vary=$country}
  <li>{$name}</li>
{/topProducts}