Doctrine Profiler Bundle Laravel Package

Getting Started

Install the bundle with Composer:

composer require --dev pixers/doctrine-profiler-bundle

Because it is a development-only tool, require it as a --dev dependency unless you have a specific staging use case.

Register the bundle. On older Symfony (3.x / pre-Flex) add it to app/AppKernel.php:

if (in_array($this->getEnvironment(), ['dev', 'test'])) {
    $bundles[] = new Pixers\DoctrineProfilerBundle\PixersDoctrineProfilerBundle();
}

On Symfony 4+/Flex, add it manually to config/bundles.php (there is no recipe autoloading):

return [
    // ...
    Pixers\DoctrineProfilerBundle\PixersDoctrineProfilerBundle::class => ['dev' => true, 'test' => true],
];

Where to look first. Run the app in dev, execute a request that touches the database, and open the Symfony Web Profiler → Doctrine panel. Each logged query will show the call stack that produced it, so you can immediately see which PHP code fired the query instead of guessing from the SQL alone.

First use case. Debugging N+1 problems: load a list page, open the Doctrine panel, and read the stack traces of the repeated queries. The trace tells you whether the extra queries come from a Twig loop, a serializer, or a lazy-loaded association.

Implementation Patterns

Dev/test-only wiring. The bundle is expensive (capturing a backtrace per query allocates memory and slows requests). Guard registration and config by environment so it never activates in prod. The common pattern:

# config/packages/dev/pixers_doctrine_profiler.yaml
pixers_doctrine_profiler:
    enabled: true
    # depth/backtrace-related options, depending on the version
    max_depth: 15

N+1 hunting workflow. Combine the profiler's stack traces with Doctrine's query count in the toolbar: the count exposes the symptom (e.g. 120 queries), and this bundle's traces expose the cause (the Twig template line or repository method that repeatedly triggered hydration).

Repositories and services. When a query originates inside a shared repository method, the stack trace surfaces every caller. Use that to decide between eager fetching (JOIN ... FETCH), batch loading, or a Criteria/IN-based secondary query.

Integration with functional tests. In test environment, enable the profiler and read $client->getProfile()->getCollector('db') to assert query counts. The bundle's stack traces help when a regression test starts reporting "unexpectedly 20 queries" and you need to know which call site grew.

Complementing other tools. Use it alongside:

• doctrine/doctrine-bundle's built-in query logging (SQL + params),
• the Web Profiler timeline (which shows where in the request the DB time lands),
• EXPLAIN for the slow queries the profiler flags.

The bundle shows the source of the query; the timing panel shows the cost.

Scoping the noise. If your app runs many routine queries (cache warmers, security lookups, schema checks), configure any exclusion/listener options the bundle provides to avoid generating backtraces for queries you do not care about, keeping the panel readable.

Gotchas and Tips

Maintenance status. Development stalled around 2019, but a newer 1.0.8 tag has since landed (see below), so the package is not fully abandoned — expect slow, small maintenance releases rather than new features. On modern Symfony (5.4+/6.x) and DoctrineBundle 2.x you may still need to relax composer constraints, patch the bundle, or fork it. Check that the bundle's compiler passes and Profiler hooks still align with the doctrine data collector of your DoctrineBundle version before assuming the panel just works.

1.0.8 changed the templating backend. v1.0.8 replaced the deprecated templating service with the Twig service for rendering the panel templates. Practical consequences:

• Symfony's templating component/engine (deprecated in 2.8, removed in 4.0) is no longer required for the panel — so this tag is materially friendlier to Symfony 4+/5 projects that previously failed or needed a shim.
• The bundle now expects twig (the twig service, normally from symfony/twig-bundle) to be present. On API-only apps that never installed Twig, the profiler panel template will fail to render — install symfony/twig-bundle in dev or skip the bundle.
• If you had a local patch/override for the templating dependency, drop it and re-test before upgrading, otherwise you may be double-patching.
• No config keys, collector names, or public API changed — this is a drop-in upgrade; re-run bin/console cache:clear after updating so the compiled container picks up the new service reference.

Silent absence of traces. If queries appear but no stack traces do:

• confirm the bundle is registered for the environment actually used (dev vs test),
• confirm profiler: enabled: true and collect: true in the Web Profiler config,
• clear the Symfony cache (bin/console cache:clear) after changing bundle/config files,
• verify you are viewing a request profile (CLI commands do not produce web profiles the same way).

Memory and speed. Backtrace capture can be the difference between a 200 ms and a 2 s page on query-heavy pages. If a request hangs, temporarily disable the bundle or lower the configured depth.

Never ship to prod. Even with enabled: false, keeping the bundle out of the prod autoload path (require-dev + environment-restricted bundle registration) avoids accidental activation and unused-class overhead.

Stack trace readability. Internal Doctrine frames (unit of work, hydrators) dominate traces. Read from the bottom up — the first application-level frame (your controller, repository, Twig extension) is the actionable call site. Filtering by your namespace in the profiler UI speeds this up dramatically.

Extension points. The collector follows the standard Symfony DataCollector pattern. If you need custom annotations (e.g. tagging queries by feature), extend the collector or wrap your Connection/EntityManager rather than modifying vendor code; the bundle is small enough that subclassing a listener is usually cleaner than forking.

Long-lived workers. Doctrine profilers are stateful per request. In Messenger workers, RoadRunner/Swoole, or long-running processes, backtrace buffers can accumulate or report misleading request boundaries — disable the bundle for those runtimes.

Version pinning. Releases are infrequent and small, so pin the exact version in composer.json (e.g. 1.0.8) and document any constraint overrides in your README, so future upgrades of Symfony/Doctrine don't silently break dev tooling.