Cache review
A development tool that helps developers review and analyze how Drupal's Internal Page Cache (IPC) and Dynamic Page Cache (DPC) work by providing visual indicators and demo pages.
cache_review
Overview
Cache Review provides comprehensive tools to help Drupal developers understand and analyze the caching mechanisms of Drupal's Internal Page Cache (IPC, for anonymous users) and Dynamic Page Cache (DPC, for all users). The module visually marks each element on the page with cache status indicators (C for cached, L for lazy-built, N for no specific cache properties), making it easy to identify which parts of a page are being cached and how.
The module displays a fixed "Page Cache Status" panel at the bottom of every page showing real-time information about cache hit/miss status, auto-placeholder conditions, and detailed cache metadata for each element. By hovering over cache markers, developers can see the exact cache contexts, tags, and max-age settings applied to each render element.
Additionally, Cache Review provides several demonstration pages that showcase different caching scenarios and behaviors, allowing developers to experiment with cache settings and observe the results immediately. This is particularly useful for learning how cache bubbling works, when lazy builders are used, and how different cache contexts affect page cacheability.
Note: This module is intended for development environments only and should not be used in production.
Features
- Visual cache status indicators on page elements: C (cached), L (lazy-built), N (no cache properties)
- Fixed Page Cache Status panel showing IPC/DPC hit/miss status, auto_placeholder_conditions, and Big Pipe module status
- Tooltip display of detailed cache metadata (contexts, tags, max-age) on hover
- Multiple demonstration pages showcasing different caching scenarios and behaviors
- Configurable framing options to display all items, only lazy-built items, only cached items, or disable framing entirely
- Option to analyze cache information on admin pages
- Custom HTML ID attributes can be specified for targeted cache analysis
- Block plugins demonstrating lazy builder and non-lazy builder caching patterns
- Service decorators that wrap Drupal's render cache and renderer to inject cache visualization
Use Cases
Learning Drupal's cache system
New Drupal developers can use the demo pages at /cache-review to understand how different cache settings affect page cacheability. Each demo page shows elements with various cache configurations (max-age, contexts, tags, keys) and their resulting cache behavior.
Debugging cache issues
When a page unexpectedly shows stale content or doesn't cache properly, developers can enable Cache Review to see which elements have problematic cache settings. The 'N' markers with bold styling indicate elements whose cache properties match auto_placeholder_conditions, potentially causing cache bubbling issues.
Optimizing render performance
By identifying which elements are cached (C), lazy-built (L), or uncached (N), developers can make informed decisions about where to add cache keys, adjust max-age values, or implement lazy builders to improve page performance.
Understanding lazy builders and placeholders
The demo pages demonstrate how #lazy_builder, #create_placeholder, and auto-placeholdering work together. Developers can see when Drupal automatically creates placeholders based on auto_placeholder_conditions and how this affects the page's overall cacheability.
Testing cache invalidation
By observing the time values displayed in demo page elements, developers can verify that cache tags are working correctly. Elements from cache show older timestamps, while freshly rendered elements show current time.
Tips
- Use the browser console to view detailed cache metadata for elements when more information is needed beyond what tooltips display
- Experiment by modifying cache settings in the controller (CacheReviewController.php) and observing the visual changes on demo pages
- Pay attention to elements marked with bold C or N indicators - these have cache properties matching auto_placeholder_conditions and may affect page cacheability
- When debugging, start with 'Frame all items' mode to get a complete picture, then narrow down using 'Frame only cached items' or 'Frame only lazy built items'
- Remember that IPC (Internal Page Cache) only affects anonymous users, while DPC (Dynamic Page Cache) affects all users
- The time displayed on each element helps identify cached vs fresh content - cached elements show older timestamps
Technical Details
Admin Pages 1
/admin/config/cache-review
Configure how Cache Review displays cache information on pages. Control which elements are framed with cache indicators and whether admin pages should be analyzed.
Hooks 2
hook_preprocess_html
Attaches the cache_review library to all pages to enable cache visualization CSS and JavaScript.
hook_help
Provides help text for the Cache Review module on the help page, explaining how to use the cache status display and demo pages.
Troubleshooting 4
Verify the module is enabled and check that you're not on an admin route (unless 'Check cache information on admin pages' is enabled). Also ensure JS/CSS assets are loading correctly.
This typically means elements lack cache keys. Only elements with #cache['keys'] defined can be cached separately. Check if the render arrays include proper cache metadata.
Look for elements with cache contexts like 'user' or 'session' that prevent page caching. These should ideally be wrapped in lazy builders. The demo page at /cache-review/uncacheable-lazy-keys demonstrates this scenario.
By default, admin routes are excluded. Go to /admin/config/cache-review and enable 'Check cache information on admin pages' to analyze admin pages.
Security Notes 3
- This module is intended for development environments only - do not use in production as it exposes internal cache metadata
- The module decorates core services which may impact performance - disable when not actively debugging
- Cache information tooltips may reveal implementation details that should not be exposed to end users