MODX caching: clearing specific caches without flushing everything

The problem: stale content after updates

When you update a template variable or snippet in MODX, visitors may still see old markup because the resource cache wasn't invalidated. At the same time, rebuilding the entire cache every time is slow and unnecessary. The solution is to clear only the caches that changed, using MODX's cache manager with precise context targeting.

How MODX organizes its caches

MODX Revolution maintains three distinct cache types that serve different purposes:

• Resource cache – stores the final parsed HTML for each resource, per context (web, mgr, api)
• Query cache – caches the results of xPDO database queries to avoid repeated SQL calls
• Object cache – holds serialized PHP objects like snippet output or custom service data

All three are managed by the xPDOCacheManager, which uses the system setting cache_default_handler to determine where the data is stored (file-based by default).

Worked example: selective cache clearing after content updates

Suppose you have a snippet that displays dynamic content and you want to clear only the resource cache for the web context after updating it:

// In your snippet or plugin, after making content changes
$modx->cacheManager->deleteCache('resource', ['context' => 'web']);

// You can also clear specific resources
$modx->cacheManager->deleteCache('resource', ['resources' => [123, 456]]);

// Clear query cache for a specific context
$modx->cacheManager->deleteCache('query', ['context' => 'web']);

This approach ensures that only the affected caches are invalidated, keeping other cached data intact for better performance.

Trade-offs and important limitations

While selective cache clearing is more efficient, there are important considerations:

1. Cache expiration – Long cache_expires values can still serve stale content if you forget to clear after updates
2. Handler changes – Switching cache handlers without flushing first can cause format mismatches and fatal errors
3. Context isolation – Remember that caches are separated by context, so clearing mgr won't affect web

The safest approach is to implement cache clearing as part of your content update workflow and always flush completely when changing handlers.

Verification steps

1. Check active handler – View modx/cache/logs/cache.log after requests to confirm which handler is being used
2. Monitor context separation – Request a front-end page and check for X-Cache-Hit headers, then verify manager pages have different caching behavior
3. Test the clearing logic – Make a content change, run your cache clearing code, then verify the updated content appears

Actionable next steps

Start by implementing selective cache clearing in your content update process. Identify which cache types your content affects and clear only those. For production environments, consider switching to APCu or Redis handlers for better performance, but always flush existing caches first. Test your implementation thoroughly to ensure users see fresh content without unnecessary cache rebuilds.