Who this is for. Developers and site operators answering "why is this page stale?" or "why did the whole site slow down after an edit?". Afterwards you know what clears itself on publish, what never does, and when to reach for the manual clear.
Invalidation is the part of caching people guess at, and the guesses are usually too pessimistic. In its default mode the platform records what each stored page was built from, and changing any of those things clears that page. Most stale pages come from the short list of changes it deliberately does not track, or from a copy outside the server.
What clears itself: smart invalidation
When a page is stored, the platform also stores what it was built from:
- Records: every record the render touched. The record the URL resolved to, every record a template called a method on, related records reached through those calls (a post's authors, a page's parent), records fetched with
$_query, global components read by identifier, menus read by name and forms. - Listings: every kind of record the render listed. A module listing route, a getter that returned a collection, and any
$_querycall,findOneBy()included, each register a listing of that record type, narrowed to the current site and no further. A listing of one blog's posts is registered as "posts of this site".
Then, when content changes:
- Saving or publishing a record clears every page that touched that record.
- Creating or deleting a record clears every page that listed its type on its site, because a list may now have one more or one less. A new post in one blog therefore clears the listing pages of every blog on the site, and a new page clears every page that called
$_queryfor pages. - A scheduled publish or expiry clears both, when it happens, as if the record had been saved.
- Saving a draft clears nothing, because nothing visible changed.
The clearing runs as a background job shortly after the save, and the jobs for repeated saves of the same record within the same 30-second window are collapsed into one. Where CDN caching for pages is on, the same job purges those URLs from the CDN. When one change would clear more than 50 stored pages, the platform clears the whole page cache of each environment concerned instead, so a save on a busy, heavily cross-linked site can send every visitor to a render for a while.
What it never sees
Some changes are excluded on purpose, and none of them clears a stored page:
| Change | Why a page stays stale | What to do |
|---|---|---|
| A setting, in any module | Settings are excluded by design; a settings change needs a full clear | Clear the environment's cache after changing a setting that affects output |
| A user or person record, or their custom fields | People and users are excluded, so renaming a person whose name appears on pages leaves every stored page with the old name | Clear the cache, or save the records concerned |
| The passage of time | "Today's events", "new" badges, countdowns and "published 3 days ago" change without a save | Give that template a lifetime that ends when the content changes (the other controls) |
| Data from outside the platform | A feed, a price from another system or a file uploaded over FTP is not a record | A short lifetime on the page, or load the data in the browser |
| A new redirect | The page cache is answered before redirects are checked, so a URL that already has a stored page keeps serving it instead of redirecting | Clear the cache after adding redirects for URLs that are live. Editing or deleting an existing redirect purges that redirect from the CDN on its own |
| The visitor's browser | A browser may keep its own copy for the rest of the page's lifetime | Nothing on the server reaches it (the CDN and the browser) |
Two cases might look like exceptions, and are not. A component placed on a page is part of that page's revision, so editing it is a save of the page. And content read from another record, such as a footer read from a global component or a promotion read from another page, is tracked through the calls that read it, so saving that record clears every page that showed it.
The three clear modes
Cache settings › Cache clear mode decides how much a change clears:
- Smart, the default and the recommendation: only the pages that used what changed.
- Purge: any tracked change clears the stored pages of every site and environment of the account, and their CDN copies. Nothing is ever stale, and every save sends every visitor to a render until the cache refills. Only worth it on a small site whose pages all depend on each other.
- Manual: changes clear nothing. Pages change when they expire or when someone clears the cache. Suits a site whose content changes on a schedule.
The exclusions above apply in every mode: a settings change does not trigger a purge either.
What a deploy clears
A push to the branch connected to an environment pulls the code and then clears, for every environment that shares that site folder, the stored pages and their CDN copies, the compiled templates and the CDN's copies of theme files. A template change is therefore live for every visitor as soon as the deploy finishes, and a deploy is also a full clear: the first visitors afterwards wait for renders. Resized images are not cleared by a deploy, and browsers keep theme files until their URLs change (theme files).
The manual clear
Each environment in the admin's list of a site's environments has a Clear Cache action, available to super administrators. It removes that environment's stored pages and compiled templates, and purges the CDN's copies of its pages, images and theme files. It does not delete resized image files. An environment without a primary hostname cannot be cleared: the action answers "The cache cannot be cleared for environments without primary hostname".
It is the right call:
- after changing a setting that affects what pages show;
- after editing people or users whose details appear on pages;
- after adding redirects for URLs that already have stored pages, which is every go-live of a replacement site;
- after adding a pattern to Response cache exclusions, which stops new copies being stored but leaves existing ones;
- on a Twig site, after a template reached the server without a deploy (compiled templates);
- on a site in Manual mode, after a batch of changes.
It is the wrong call as a habit after every edit. Smart invalidation already did the precise version, and a full clear makes every visitor wait for a render until the cache refills, which on a large site during business hours is real load on the database. If an edit does not appear, find out which copy is stale first (is this copy stale).