Skip to content

Extending

The module defines no hooks, events or plugin types of its own. Modules take part through a discovery file, through the cacheability of their responses, and through two services.

The response_cache.yml file

Discovered with core's YamlDiscovery from every installed module's root directory. The format is on the Configuration page and in response_filesystem_cache.api.php.

Response cacheability

What a controller returns decides whether and for how long its response is cached. See Controlling it from a controller.

To have a file refresh when content changes, return a CacheableResponse and declare its dependencies:

use Drupal\Core\Cache\CacheableJsonResponse;
use Drupal\Core\Cache\CacheableMetadata;

$response = new CacheableJsonResponse($data);
$response->addCacheableDependency(
  (new CacheableMetadata())->setCacheTags(['node_list:product']),
);
return $response;

Saving any product node then invalidates node_list:product, and the file stops being served on the next request.

Services

response_filesystem_cache.mapping_manager

Implements ResponseCacheMappingManagerInterface, also available by that interface name for autowiring.

Method Returns
getMappings() The enabled mappings, keyed by module.id.
getAllMappings() Every valid discovered mapping, enabled or not.
matchPath(string $path) The mapping governing a processed request path (see requestPath() below), or NULL.
invalidate() Nothing. Discards the discovery cache so the files are read again.

Each mapping is an array with the keys id, module, path_prefix, uri_prefix, query_allowlist and max_files.

Constants:

Constant Value
URI_NAMESPACE public://response_filesystem_cache
DEFAULT_MAX_FILES 10000
SETTINGS response_filesystem_cache.settings
CACHE_ID The cache.discovery ID holding the discovered mappings.

response_filesystem_cache.file_cache

ResponseFileCache, also available by its class name. It makes the caching decisions and manages the files.

Method Purpose
requestPath(Request) The request path after the inbound path processors: decoded, without a language prefix, with any alias resolved.
isRequestEligible(Request) The request-side checks.
isResponseShareable(Response) The developer-intent checks: Cache-Control, max-age, cache contexts. Must run before core's FinishResponseSubscriber.
isResponseStorable(Response) Status, cookies, body type.
buildCacheId(array $mapping, Request) The cache key, or NULL when the request must not be cached.
lookup(string $cid) A still-valid file descriptor, or NULL.
write(string $cid, array $mapping, Request, Response) Writes and indexes a file. Failures are logged and return FALSE.
deleteMapping(array $mapping) Deletes one mapping's files.
deleteAll() Deletes every file and index entry.
garbageCollect() Deletes files whose index entry is gone. Returns the count.

To clear one mapping's files from code, for example after a bulk import that does not invalidate tags:

$manager = \Drupal::service('response_filesystem_cache.mapping_manager');
$file_cache = \Drupal::service('response_filesystem_cache.file_cache');
$file_cache->deleteMapping($manager->getAllMappings()['my_module.products']);

Index entries for the deleted files stay in the cache bin until they are invalidated. A lookup that finds an entry without its file drops the entry and regenerates the file.

Cache bin

Index entries live in the response_filesystem_cache bin. Each cache file uses two entries: one keyed by the request, and one keyed by the file, which cron reads to tell a live file from a spent one. Each mapping also has one entry counting its files for max_files. Any cache backend works; see Troubleshooting for the database backend's row limit.