Understanding caches
A cache holds stored results that make pages faster; Exponential has many (content view, template, INI, HTTP, static, SQL query, response) (Glossary). Learners meet caches when a change they made does not appear. This page explains which cache to suspect and how to clear only that one.
Contents
- Why caches exist
- The three caches you meet first
- Clearing in the administration
- Clearing from the shell
- When the page is still old
- Cache problem or real error
Why caches exist
Building a page means reading settings, finding templates, compiling them and fetching content. Caches keep the results, so the next visitor gets the page without that work. Exponential renews them when content is published, "so clearing by hand is the exception" (Which cache do I clear?).
The three caches you meet first
| You changed | Cache to clear | Typical exercise |
|---|---|---|
| Content, and a page shows the old version | Content (content view cache) | Publishing in project 2 |
| A template or a design file, or you added a new template path | Template caches | project 3 |
A setting in an .ini file | INI caches | project 5 |
| You do not know, or several of these | All caches | Rarely: everything is rebuilt afterwards |
Source: Which cache do I clear?. The rule: clear the smallest cache that solves the problem.
Clearing in the administration
- Quick: the Clear cache box in the right column: choose a cache and click Clear.
- Full choice: Setup > Cache management. The Caches page groups every cache (Content and views, Templates, INI and settings, Images, Pages, queries and the server, Other) and has buttons for content, template, INI or all caches.
You need the setup/managecache policy. The administrator of your study site has it.
Clearing from the shell
From the installation root (Caches):
php bin/php/ezcache.php --clear-tag=content --allow-root-user # the content caches
php bin/php/ezcache.php --clear-tag=template --allow-root-user # the template caches
php bin/php/ezcache.php --clear-tag=ini --allow-root-user # the settings caches
php bin/php/ezcache.php --clear-all --allow-root-user # everything
php bin/php/console exp:cache clear --id=content --dry-run --allow-root-user # what would be clearedLeave out --allow-root-user when you are not root. A dry run is a good habit: it shows what a clear would
remove, with sizes.
The template guide adds one rule for overrides: a new template path needs the override and template caches cleared once (Templates and design).
When the page is still old
| Cause | What to do | Source |
|---|---|---|
| The browser shows its own copy | Reload with Shift held, or use a private window | Which cache do I clear? |
| Velocity's response cache answers for a few seconds | php bin/php/console exp:velocity cache clear --apply, or wait | Caches |
| A running Velocity holds settings in memory | php bin/php/console exp:velocity restart --allow-root-user after clearing INI caches | Caches |
| A settings change on a server with PHP-FPM | The web server's PHP must reload; ask whoever deploys | Which cache do I clear? |
On a study site served with the php engine, the first two rows are the usual ones.
Cache problem or real error
| Sign | Likely |
|---|---|
| The old content or markup appears, without an error | A cache |
| An error page, a white page or a 500 status | A real error: read the logs (Reading logs and errors) |
| The change appears in the administration's preview but not on the site | A cache on the site side |
| The change appears nowhere, even after clearing all caches | The change was not saved where you think: check the siteaccess and the file (Understanding siteaccesses and settings) |
Write in your study journal each time a cache was the answer, with which one. After a few weeks you will know your caches by heart.
Related pages
- Caches
- Which cache do I clear?
- Reading logs and errors
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.