Page Cache
Textstem can save each rendered public page as an HTML file, so repeat requests skip loading the page and rendering its blocks. The cache is off by default. For how editors check and clear it in the admin, see Caching Pages in the User Guide.
The cache is Medialight\Textstem\Domain\Pages\PageCache. PageRenderingService asks it for a cached copy before it loads the page, and saves the rendered HTML afterwards.
Settings
The settings are under cache in config/textstemapp.php, and each reads an env variable:
| Config key | Env variable | Default | Purpose |
|---|---|---|---|
cache.enabled |
WRANGLER_CACHE_ENABLE |
false |
Turns the cache on |
cache.expire |
WRANGLER_CACHE_TTL |
3600 |
Seconds a cached copy is kept; 0 keeps it until the cache is cleared |
cache.key |
WRANGLER_CACHE_MODE |
private |
The strategy: private or public (see below) |
cache.withquery |
WRANGLER_CACHE_WITHQUERY |
false |
private strategy only: true caches each query string separately |
WRANGLER_CACHE_ENABLE=true
WRANGLER_CACHE_TTL=3600
WRANGLER_CACHE_MODE=private
WRANGLER_CACHE_WITHQUERY=false
If the config is cached, run php artisan config:cache again after changing .env.
The cache folder is created the first time the cache is used. If it can't be created or written to, the cache turns itself off and logs cacheDirectoryPath is not writable. Page Cache will be disabled at debug level.
Strategies
Private (the default)
Files are saved in storage/page-cache/, each named by an MD5 hash of the page's path (and of its sorted query string, when WRANGLER_CACHE_WITHQUERY is on). The app serves them: every request still reaches Laravel, but a cached page is returned without loading the page or rendering its blocks.
Requests with a query string, such as ?page=2, are only cached when WRANGLER_CACHE_WITHQUERY is true.
Public
Files are saved in public/page-cache/, in folders that follow the page's url: /about/team is saved as public/page-cache/about/team.html, and the home page as public/page-cache/__INDEX__.html. Characters other than letters, digits, spaces and -_~,;[](). are removed from each part of the path. Requests with a query string are never cached with this strategy, whatever WRANGLER_CACHE_WITHQUERY says.
Because the files are at predictable paths under public/, the web server can serve them without reaching the app. On Apache, add these rules to public/.htaccess, before Laravel's own rewrite rules:
RewriteCond %{REQUEST_URI} ^/?$
RewriteCond %{DOCUMENT_ROOT}/page-cache/__INDEX__.html -f
RewriteRule .? page-cache/__INDEX__.html [L]
RewriteCond %{DOCUMENT_ROOT}/page-cache%{REQUEST_URI}.html -f
RewriteRule . page-cache%{REQUEST_URI}.html [L]
Without the rules the strategy still works, but the app serves the files, as with the private strategy.
Files the web server serves bypass the app entirely, so:
- They don't expire. The cache's lifetime is checked only when the app serves a file; a file the web server serves stays until the cache is cleared.
- Every visitor gets them, signed in or not.
%{REQUEST_URI}doesn't include the query string, so a request with a query string is served the cached file for its path.
What is cached
A page is saved only when all of these are true:
- The cache is on and its folder is writable.
- The request is a GET.
- The request has no query string, or the strategy is
privateandWRANGLER_CACHE_WITHQUERYis on. - The visitor isn't signed in.
- The page is published and its access is Public. Private and password-protected pages are never cached.
- The page was found and rendered. Redirect pages, and pages where a block redirects while rendering, are not cached.
Being signed in only stops a page being saved. The cache is checked before the page is loaded, so once a copy exists it is served to everyone, signed-in users included, and the page's access rules aren't checked again. That is why only public pages are saved, and why the cache is cleared when a page's access, published status or address changes (see below).
Earlier versions of the package also cached password-protected pages: once a visitor unlocked one, the cached copy was served to anyone who requested its url. After updating from one of them, clear the page cache once (see below), so no copy an older version saved is left.
A saved file ends with an HTML comment giving its cache key, the request url and the time it was saved. When the app serves a cached file it also adds <!-- app cache --> to the end, which shows whether a response came from the cache.
Clearing the cache
The whole page cache is cleared automatically when a page is created or deleted, or saved with a change to its access, enabled (published status), url, greedy or redirect column (PageCache::CLEARING_COLUMNS): for example when it is made password-protected, unpublished, moved or turned into a redirect. A new page can take over a path that a greedy parent's copy was cached for, and a moved page leaves its copy at the old path. The whole cache goes, not just that page's file, because copies of other pages (their menus, say, or a greedy page's sub-paths) can't be traced back to it.
Drafts of live pages (working copies, from content approval) are never served at a public address, so creating, editing or deleting one leaves the cache alone; publishing a draft saves the live page, which clears the cache if one of those columns changed. This runs from the page model's created, saved and deleted events, so a change made with a query builder update() doesn't trigger it. If clearing fails, the error is reported and the page still saves.
Other saves (blocks, title, menu order and so on) don't clear the cache: a page's cached copy is replaced when it expires. To clear the cache straight away:
- In the admin, choose Clear page cache from the settings menu (the cog icon in the top bar), or Clear Cache on Tools → Cache Manager. Both send
POST /textstem/admin/clear-page-cache, which deletes the whole cache folder and then flushes Laravel's application cache (Cache::flush()). It needs thepublish wranglerpagesormanage settingspermission (PageCache::mayClear()), and the settings menu only shows Clear page cache to those people; the Cache Manager is for super admins. AGETis refused. The AI assistant'sclear_page_cachetool clears the page files under the same permission rule. - In code, call
PageCache::getInstance()->clearAll().
php artisan cache:manage clear clears Laravel's own caches (application, route, config and view), not the page files.
The clear request also takes a url parameter (for example url=about/team). With it, only {url}.html in the cache folder is deleted, which matches how the public strategy names its files; it has no effect on private files, whose names are hashes.
To run your own clean-up as well, for example to purge a CDN, add an App\Actions\ClearCache class with a handle($url) method. It is called after the page files are cleared, with the url parameter (an empty string when clearing everything). If it returns a truthy value, the Cache::flush() that would follow is skipped.
Cache Manager
Tools → Cache Manager in the admin (super admins only) shows whether the cache is on, its lifetime, its strategy, the cache folder's path and whether it exists and is writable. With the public strategy it writes a test file, cache-test.html, to the cache folder and loads /cache-test in a frame: "[public cache]" means the web server served the file, and "[application cache]" means the app did.
With React rendering
When React rendering is on, public pages don't go through PageCache and no files are written. Instead, the built components array for each page is kept in Laravel's cache store, under a key starting textstem.public-page.. It uses the same WRANGLER_CACHE_ENABLE, WRANGLER_CACHE_TTL and WRANGLER_CACHE_WITHQUERY settings; WRANGLER_CACHE_MODE and the .htaccess rules don't apply.
It is skipped for signed-in users, for requests other than GET and for pages whose access isn't public, so signed-in users always see the current version. Clear page cache clears it, as it flushes Laravel's cache, and so does php artisan cache:clear. The automatic clearing when a page is created, deleted or changed as described above doesn't touch it; it isn't needed here, because the page is loaded, and its access checked, before this cache is read.