Usage¶
How a request is handled¶
- After authentication and before routing, the module checks whether the request is eligible and whether its path falls under an enabled mapping.
- If an index entry for the request's cache key is still valid and its file exists, the file is returned. The route does not run.
- Otherwise the route runs as usual. Before core rewrites
Cache-Control, the module records whether the response may be shared. - At the end of the response cycle, if the response is shareable and storable, it is written to its file and indexed.
A hit carries the header X-Response-Filesystem-Cache: HIT.
What gets cached¶
A cache file is served without a route access check, so only responses that are the same for every anonymous visitor are eligible.
A request takes part only if all of these hold:
- The method is
GETorHEAD. - The visitor is anonymous, with no session cookie and no non-empty
Authorizationheader. (Drupal's.htaccessgives every request on Apache an empty one.) - The site is not in maintenance mode.
- Every query parameter is listed in the mapping's
query_allowlist. - No path segment below the prefix is a dotfile, a traversal segment, or a
name with an executable extension such as
.php.
A response is stored only if all of these hold:
- The status is exactly
200. - It sets no cookie.
- It is not a
StreamedResponseorBinaryFileResponse, and its body is a string. - The controller did not call
setPrivate()or setno-store. - It declares no
Varyheader other thanAccept-Encoding. - If it implements
CacheableResponseInterface, its max-age is not0, and its cache contexts are limited tourlandlanguages, including parameterised forms such asurl.query_argsandlanguages:language_interface. A content-language context (languages:language_content, or barelanguages) is accepted only while content language detection is not customised, because the key does not encode the content language.
The cache key is made of the scheme and host, the mapping, the interface and URL languages, the path below the prefix, and the allowlisted query parameters in sorted order. The path is the one routing sees: decoded, with a language prefix removed and an alias resolved.
Controlling it from a controller¶
| The controller does | Result |
|---|---|
| nothing | Cached, on the strength of the request checks |
$response->setPublic() |
Cached |
$response->setPrivate() |
Never cached |
sets Cache-Control: no-store |
Never cached |
returns a CacheableResponse with tags |
Cached, and invalidated by those tags |
returns a CacheableResponse with max-age 300 |
Cached for at most 300 seconds |
adds a user or user.permissions cache context |
Never cached |
sets Vary: Origin or any Vary other than Accept-Encoding |
Never cached |
Symfony composes Cache-Control: no-cache, private for a response whose
header was never set, so private alone is not taken as intent. The module
reads the header before core replaces it, and only when it differs from what
Symfony composes. setPrivate() is the supported way to say "never cache this
response".
What a hit returns¶
Status 200, the stored body, X-Response-Filesystem-Cache: HIT, and these
headers from the original response: Content-Type with its parameters,
Content-Disposition, Link and X-Robots-Tag. Other headers the controller
set are not stored. Access-Control-Allow-Origin in particular is left out,
because a controller that reflects the request's Origin would hand one
origin's grant to every other. Headers that event subscribers and middleware
add, including core's CORS configuration, are added as on any request.
Invalidation¶
Each index entry carries the generating response's cache tags and expires with its max-age. Every entry also depends on:
routes: files are served before routing runs, so a router rebuild, such as a module install or a changed route requirement, discards every file.config:user.role.anonymous: granting or revoking a permission for anonymous visitors discards every file.
A response that declares no cache tags is not invalidated by content changes. It lives until a router rebuild, a change to the anonymous role, or a cache rebuild.
| Event | Effect |
|---|---|
| A tag on the response is invalidated | The file stops being served on the next request |
| The response's max-age passes | The file stops being served on the next request |
| A mapping is turned off | Its files are deleted |
drush cr |
Every file is deleted |
| Cron | Files whose index entry is gone are deleted |
| The module is uninstalled | The directory is deleted |