Esi Debug Bundle Laravel Package

Getting Started

This bundle is archived and targets the Symfony 2/3 era. Before writing any code, verify compatibility against your Symfony version — on Symfony 4+ assume it will not boot and plan an alternative (see Gotchas). If you are on a legacy app:

1. Install as a dev dependency:

   composer require --dev nelmio/esi-debug-bundle
   

2. Register it only in the dev environment in app/AppKernel.php:

   if (in_array($this->getEnvironment(), ['dev', 'test'], true)) {
       $bundles[] = new Nelmio\EsiDebugBundle\NelmioEsiDebugBundle();
   }
   

3. Make sure ESI is actually enabled and requests pass through a caching layer:

   # app/config/config.yml
   framework:
       esi: true
   

   Your front controller must route through AppCache / HttpCache (or a reverse proxy like Varnish), otherwise there is no ESI layer to inspect.
4. Load a page composed of fragments ({{ render_esi(controller('...')) }}), then open the Symfony profiler and inspect the ESI panel in the web debug toolbar.

First use case: confirm which fragments were rendered as ESI subrequests and what the cache did with each one, instead of guessing from a blank page or stale content.

Implementation Patterns

Dev-only toolbar inspection. The primary workflow is browser-driven: render a page, open the profiler, and read the ESI panel to see the subrequest tree and cache status per fragment. Treat it as a read-only diagnostic, not part of application logic.

Compose a "cache rehearsal" page. Build a route that fans out to several ESI fragments with different s-maxage, Vary, and cookie behavior. Use it as a repeatable fixture to compare behavior before/after config changes — the debug output becomes your regression signal.

Pair with native cache headers. Cross-check the bundle's view against X-Symfony-Cache (emitted by HttpCache) or your proxy's X-Cache header. The bundle's panel is the summary; the raw headers are the ground truth when they disagree.

Fragment-level workflows. Typical checks:

• Is a fragment being re-fetched on every request (cache miss) when it should be shared?
• Does changing a fragment's TTL show up in the debug info?
• Do personalized fragments (session/cookie-dependent) correctly bypass shared caching?

Isolate debugging from production. Register the bundle only in dev, and keep any instrumentation-driven routes behind the dev firewall. Do not let fragment-testing routes leak into prod routing.

Gotchas and Tips

• Archived and unmaintained. No fixes, no security patches, no support for modern Symfony. Check composer.json constraints first; on Symfony 4+ this is effectively a dead end.
• Modern alternatives. Use the Symfony profiler's built-in cache panel with HttpCache, FOSHttpCacheBundle for proxy-aware debugging, or plain X-Symfony-Cache / proxy X-Cache headers. These cover most of what this bundle did.
• ESI needs a cache in front. If your request bypasses AppCache/HttpCache/Varnish (e.g., direct kernel invocation in tests or php -S without the cache wrapper), you get zero ESI activity and an empty panel — this is the most common "it's broken" false alarm.
• The toolbar can poison your cache. Debug toolbars inject cookies and headers; the Symfony debug toolbar in particular sets a cookie that makes responses uncacheable. Exercise ESI behavior with the toolbar disabled (or in a separate environment) before trusting cache-hit numbers.
• Nested ESI and subrequest depth. Deeply nested fragments and subrequests make the panel noisy and can obscure which parent triggered a miss. Flatten your fragment tree when diagnosing.
• Session/cookie-driven fragments silently disable sharing. A single Set-Cookie on a fragment turns it private; the panel will show misses that look like a config bug but are correct behavior.
• Extension points are thin. There is no meaningful plugin surface; if you need custom behavior, fork it and adapt, or migrate to a maintained profiler integration rather than patching in place.
• Debugging checklist when output is confusing: confirm framework.esi: true, confirm the request hit HttpCache, check X-Symfony-Cache on the parent and each fragment, then re-render with the toolbar disabled and compare.