Changing the Cache File Name for a Resource

Evolution CMS stores file-based page cache entries using a predictable key. In classic installs that key is often based on the resource ID, which produces files such as docid_123.pageCache.php. If you need a different cache naming strategy, the key point is the OnMakePageCacheKey event.

The original discussion around This scenario came from a project that expected the event in one branch and could not trigger it in another. The safe conclusion is simple: custom cache file naming depends on the core version you are running. In current Evolution CMS code the hook exists in the page cache key flow, so the correct place to customize the name is the event rather than random edits in cache internals.

How the cache key is built

In the current core the cache key is generated inside the page rendering flow and then passed through OnMakePageCacheKey. That gives plugins a supported place to adjust the hash before the cache file is written.

/**
 * @internal @events OnMakePageCacheKey
 */
if ($modx->event->name !== 'OnMakePageCacheKey') {
    return;
}

$id = (int)($modx->event->params['id'] ?? 0);
$params = $modx->event->params['params'] ?? [];

$hash = 'resource-' . $id;

if (!empty($_GET['lang'])) {
    $hash .= '-lang-' . preg_replace('/[^a-z0-9_-]/i', '', $_GET['lang']);
}

$modx->event->params['hash'] = $hash;

When to use a custom key

• when the same resource is cached differently per language, domain, or audience
• when a reverse-proxy or deployment flow needs predictable cache file names
• when debugging cache collisions on complex sites

What to verify first

• check that your core version actually triggers OnMakePageCacheKey
• clear existing cache files before testing a new naming rule
• avoid using raw query strings in the key unless you intentionally want a separate cache variant

If you are working on an older branch where the event never fires, the fix is not to patch templates or snippets. The fix is to confirm the branch, inspect the cache key code path, and update to a core version where the event is present. That keeps your solution maintainable instead of tying it to a one-off hack.

This topic is a good reminder that cache customization belongs in events and supported extension points. If you need custom page cache naming, start with OnMakePageCacheKey and keep the rule small, deterministic, and easy to debug.