Skip to content

Usage

How a request is handled

  1. After authentication and before routing, the module checks whether the request is eligible and whether its path falls under an enabled mapping.
  2. 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.
  3. Otherwise the route runs as usual. Before core rewrites Cache-Control, the module records whether the response may be shared.
  4. 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 GET or HEAD.
  • The visitor is anonymous, with no session cookie and no non-empty Authorization header. (Drupal's .htaccess gives 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 StreamedResponse or BinaryFileResponse, and its body is a string.
  • The controller did not call setPrivate() or set no-store.
  • It declares no Vary header other than Accept-Encoding.
  • If it implements CacheableResponseInterface, its max-age is not 0, and its cache contexts are limited to url and languages, including parameterised forms such as url.query_args and languages:language_interface. A content-language context (languages:language_content, or bare languages) 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