Profiler Storage Bundle Laravel Package

Getting Started

This bundle is a drop-in replacement/extension for Symfony's profiler storage layer, letting you send profiler data (_profiler tokens, timelines, request traces) to a backend other than the default filesystem cache directory. The day-to-day value shows up when the request you want to inspect was served by a different PHP process than the one rendering _profiler — e.g. multiple app containers, a load balancer, or a php-fpm pool with a shared cache.

Minimal steps:

1. Install with a version constraint pinned to your Symfony major, since the last tagged release is from 2019:

   composer require sitetheory/profiler-storage-bundle
   

   Check composer why-not sitetheory/profiler-storage-bundle if resolution fails — most likely a symfony/framework-bundle constraint conflict.

2. Register the bundle using the convention for your Symfony version:

   • Symfony ≤ 3.4: add new Sitetheory\ProfilerStorageBundle\ProfilerStorageBundle() to AppKernel::registerBundles().
   • Symfony 4+: append it to config/bundles.php.

3. Inspect the bundle's DI extension first. Look at DependencyInjection/ and Resources/config/ in vendor/sitetheory/profiler-storage-bundle to find the exact config key (usually something like sitetheory_profiler_storage:) and the DSN format it accepts. Do this before writing config — the README is thin and the extension is the source of truth.

4. Wire it into the profiler. In config/packages/dev/framework.yaml (or config_dev.yml):

   framework:
       profiler:
           dsn: 'redis://redis:6379/2'   # or whatever DSN the bundle documents
   

5. First use case to validate: open two browser tabs, hit the app, then load /_profiler from a second request. If tokens survive across requests (and ideally across containers), the storage is working. If you see "Token not found", the profiler is still writing to the filesystem — verify with debug:container profiler.storage.

Implementation Patterns

Shared Redis storage across containers. The canonical workflow: run several app containers behind a proxy, point every container's framework.profiler.dsn at the same Redis instance, and browse /_profiler from any container. This is the pattern that justifies the dependency — the default FileProfilerStorage writes to var/cache/dev/profiler, which is per-container.

Environment-scoped config. Never enable this in production. Put the DSN and any bundle config under config/packages/dev/ and config/packages/test/, not the base config. A misconfigured profiler storage in prod silently accumulates request data (and potentially request payloads) in Redis.

Custom storage via ProfilerStorageInterface. If the bundle's built-in backends don't fit, implement Symfony\Component\HttpKernel\Profiler\ProfilerStorageInterface (read, write, purge, find) and alias it to profiler.storage in a compiler pass or service definition. This bundle's config is a convenience wrapper; the underlying contract is stable across Symfony versions and is the extension point to rely on.

Decorator for observability. Wrap the storage service with a decorator that logs write failures and latency:

services:
    App\Profiler\LoggingStorage:
        decorates: profiler.storage
        arguments: ['@App\Profiler\LoggingStorage.inner', '@logger']

This gives you visibility when the backend is slow without touching bundle internals — useful because profiler writes happen on the response path and a slow Redis will add latency to every dev request.

CI / local triage workflow. In integration test runs, enable the profiler and dump tokens to Redis, then inspect from the host with redis-cli or by loading /_profiler against a running dev container. This lets you debug a failing pipeline step without re-running it.

Pair with framework.profiler.collect: false when you only need the storage path (e.g. to seed data) — collecting and storing are independent knobs.

Gotchas and Tips

• Version compatibility is the biggest risk. Last release 2019-05-13, zero dependents, four stars. If you're on Symfony 5/6/7, assume the bundle won't install or won't boot without patching. Prefer Symfony's native framework.profiler.dsn (which supports HTTP/Redis/etc. in modern versions) and treat this bundle as a stopgap for 2.8–4.x.
• The profiler is debug-only. framework.profiler is disabled unless kernel.debug is true (or you force it). If _profiler returns 404 in your container, the problem is usually APP_DEBUG=0, not the storage bundle.
• Token not found across requests almost always means multiple DSNs: one container resolving to file storage, another to Redis. Verify each container with bin/console debug:container profiler.storage --show-arguments.
• Unbounded growth. Profiler data has no default TTL in Redis. The profiler:clear-style command purges by pattern, but if nothing runs it, Redis fills up. Set maxmemory-policy on the Redis database (use a dedicated DB index, not 0) and schedule purges.
• Key collisions. Use a dedicated Redis DB or namespace; profiler keys are opaque tokens and will mix with your app cache if you share a DB.
• Service override precedence. Symfony's profiler service reads profiler.storage. If your bundle config doesn't take effect, a later compiler pass or framework.profiler.dsn wins — check debug:container --show-arguments profiler.storage and debug:config framework profiler to see the final DSN.
• Failure mode is silent-ish. If the backend is unreachable, profiler writes fail but the request usually completes. Don't rely on exceptions for alerting; instrument the decorator above.
• Extension point to trust. The stable API is ProfilerStorageInterface, not this bundle's config tree. If you outgrow the bundle, swap in your own storage service without changing application code.
• Cache warmup. After changing DSN or storage backend, run bin/console cache:clear in the target environment; stale container definitions are a common cause of "my config change did nothing."