Synopsis
Response Filesystem Cache stores anonymous responses for registered paths as files in the public filesystem and serves repeat requests from those files instead of running the route. Cache files are indexed under the response's cache tags, so they stop being served when the content they were built from changes.
It is meant for read-only endpoints, such as JSON APIs, whose responses are the same for every anonymous visitor and are costly to build. Requests still boot Drupal; the cache saves the work of the route, not the bootstrap.
How it works
- Registration: a module lists path prefixes in a
MODULE.response_cache.ymlfile. Nothing is cached until a module does. - Serving: after authentication and before routing, an eligible anonymous request under a registered prefix is answered from its file when the file's index entry is still valid.
- Storing: otherwise the route runs as usual, and a response that is safe to share is written to
public://response_filesystem_cache/on the way out. - Invalidation: each file is indexed under the response's cache tags and max-age. Invalidating a tag stops the file being served on the next request. Router rebuilds, changes to the anonymous role and
drush crdiscard every file; cron deletes spent files.
What gets cached
Only GET and HEAD requests from anonymous visitors with no session cookie or credentials in an Authorization header, outside maintenance mode, whose query parameters are all on the mapping's allowlist. Only 200 responses that set no cookie, have a string body, were not marked setPrivate() or no-store, and declare no cache context other than url and languages. The cache key covers the scheme and host, language, path and allowed query parameters.
Requirements
- Drupal core 10.6, 11.3 or later, or 12.
Usage
Create a {module_name}.response_cache.yml file in the root of your module:
products:
# The path to cache, matched on segment boundaries.
path_prefix: /api/products
# Optional. Query parameters that take part in the cache key. A request
# with any other parameter is served live.
query_allowlist:
- category
- pageSite administrators can turn each mapping off at Configuration > Development > Response Filesystem Cache.
To have a file refresh when content changes, return a CacheableResponse with the right cache tags. $response->setPrivate() keeps a response out of the cache.
Documentation
Configuration, behaviour, the services for other modules, troubleshooting and upgrade notes: project.pages.drupalcode.org/response_filesystem_cache.
How this module is built
Much of this module's code, tests and documentation was drafted with an AI coding assistant (Claude Code). The maintainers review, test and take responsibility for every change, and the tests and code checks run on drupal.org's CI. Contributions follow Drupal's policy on the use of AI when contributing.
Supporting this module
Developed and maintained by Tyler Brown Cifu Shuster of FivePaths, LLC. Development sponsored by FivePaths and the San Francisco Municipal Transportation Agency.
Project information
- Project categories: Decoupled, Performance
3 sites report using this module
- Created by tbcs on , updated
Stable releases for this project are covered by the security advisory policy.
Look for the shield icon below.

