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
10 sites
47
drupal.org
development gui
cache development debugging performance page cache dynamic page cache lazy builder render cache developer tools

概要

Cache Reviewは、DrupalのInternal Page Cache（IPC、匿名ユーザー向け）とDynamic Page Cache（DPC、全ユーザー向け）のキャッシュメカニズムを理解・分析するための包括的なツールを提供します。このモジュールは、ページ上の各要素にキャッシュステータスインジケーター（C=キャッシュ済み、L=遅延ビルド、N=特定のキャッシュプロパティなし）を視覚的に表示し、ページのどの部分がどのようにキャッシュされているかを簡単に識別できるようにします。

モジュールは、すべてのページ下部に固定された「Page Cache Status」パネルを表示し、キャッシュのヒット/ミス状態、auto-placeholder条件、各要素の詳細なキャッシュメタデータをリアルタイムで表示します。キャッシュマーカーにマウスを合わせると、各render要素に適用されている正確なcache contexts、tags、max-age設定を確認できます。

さらに、Cache Reviewは様々なキャッシュシナリオと動作を示すデモページを提供しており、開発者がキャッシュ設定を試して結果を即座に確認できます。これは、cache bubblingの仕組み、lazy builderがいつ使用されるか、異なるcache contextsがページのキャッシュ可能性にどう影響するかを学ぶのに特に役立ちます。

注意: このモジュールは開発環境専用であり、本番環境では使用しないでください。

Features

  • ページ要素への視覚的なキャッシュステータスインジケーター：C（キャッシュ済み）、L（遅延ビルド）、N（キャッシュプロパティなし）
  • IPC/DPCのヒット/ミス状態、auto_placeholder_conditions、Big Pipeモジュールの状態を表示する固定Page Cache Statusパネル
  • マウスオーバーで詳細なキャッシュメタデータ（contexts、tags、max-age）をツールチップ表示
  • 様々なキャッシュシナリオと動作を示す複数のデモページ
  • 全アイテム表示、遅延ビルドアイテムのみ、キャッシュ済みアイテムのみ、フレーミング無効化の設定オプション
  • 管理ページでのキャッシュ情報分析オプション
  • 対象を絞ったキャッシュ分析用のカスタムHTML ID属性の指定
  • lazy builderと非lazy builderのキャッシュパターンを示すBlockプラグイン
  • キャッシュ可視化を注入するためにDrupalのrender cacheとrendererをラップするサービスデコレーター

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
Cache Review configuration /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
Page Cache Status panel not appearing

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.

All elements show 'N' (no cache properties) markers

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.

Page always shows MISS for DPC

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.

Cache markers not visible on admin pages

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