Doctrine Debug Bundle Laravel Package

Getting Started

Minimal Steps for Laravel Developers (Symfony Context)

While this package is Symfony-specific, Laravel developers using Symfony components (e.g., via symfony/doctrine-bundle in hybrid setups) can adapt it. Here’s how to start:

1. Install the Bundle:

   composer require sidus/doctrine-debug-bundle "~1.0"
   

2. Enable in config/bundles.php (Symfony 4+):

   return [
       // ...
       Sidus\DoctrineDebugBundle\SidusDoctrineDebugBundle::class => ['dev' => true, 'test' => true],
   ];
   

3. Clear Cache:

   php bin/console cache:clear
   

4. Trigger a Query:

   • Run a Doctrine query (e.g., via a controller or CLI command).
   • Visit /_profiler/ in your browser (Symfony Profiler must be enabled).

5. Inspect the Profiler:

   • Navigate to the Doctrine tab.
   • Click a query to see its stack trace, showing the exact code path (e.g., controller, repository, or entity method).

Note: This package is Symfony-only. For Laravel, consider alternatives like:

• Laravel Debugbar (for query logging).
• Telescope (for query inspection).
• Doctrine’s built-in logging (doctrine:query-log).

Implementation Patterns

Workflows for Symfony Developers

1. Debugging N+1 Queries:

   • Use the stack trace to identify the repository method or entity relationship causing nested queries.
   • Example: A stack trace pointing to UserRepository::findWithPosts() reveals the culprit.

2. Legacy Code Audits:

   • Trace obscure queries to their original business logic (e.g., a User::getOrders() method triggering 20+ queries).
   • Example: Stack trace shows OrderController::index() → OrderService::fetchAll() → EntityManager::createQuery().

3. Performance Profiling:

   • Correlate slow queries with specific routes or user actions (e.g., a checkout flow with 500ms queries).
   • Example: Stack trace reveals CheckoutController::process() as the bottleneck.

4. CI/CD Debugging:

   • Enable in test environments to debug failing test queries (e.g., php bin/console test --env=test).
   • Example: A test failing due to a missing WHERE clause becomes obvious via the stack trace.

Integration Tips

• Symfony Flex Projects:

  • If using Symfony 4+, ensure symfony/profiler-pack is installed (required for the Profiler UI).
  • Add to config/packages/dev/_profiler.php if not auto-loaded.

• Doctrine Event Listeners:

  • The bundle hooks into Doctrine’s onQuery event. If you have custom listeners, ensure they don’t interfere with stack trace collection.

• Hybrid Laravel/Symfony Apps:

  • If using Symfony components in Laravel (e.g., via spatie/laravel-symfony-components), enable the bundle in a microkernel or separate Symfony app.

• Customizing Stack Traces:

  • Override the bundle’s stack trace formatter by extending SidusDoctrineDebugBundle\DataCollector\DoctrineDebugDataCollector and redefining collect().

Example: Debugging a Slow Query

1. Symptom: A page load takes 2 seconds due to a slow User::findByRole() query.
2. Steps:
   • Visit /_profiler/ → Doctrine tab.
   • Click the slow query to see its stack trace:

     UserController::show() → UserRepository::findByRole() → EntityManager::createQuery()
     

   • Optimize UserRepository::findByRole() (e.g., add DISTINCT, use a join, or cache results).

Gotchas and Tips

Pitfalls

1. Profiler Not Enabled:

   • Symptom: Stack traces don’t appear.
   • Fix: Ensure WebProfilerBundle is installed and enabled in dev/test environments.

     composer require symfony/profiler-pack
     

2. Doctrine DBAL vs. ORM:

   • Symptom: Bundle doesn’t capture queries.
   • Fix: This bundle only works with Doctrine ORM (not DBAL). Use doctrine:query-log for DBAL.

3. Xdebug Dependency (Pre-v1.0.2):

   • Symptom: Stack traces are empty or incomplete.
   • Fix: Update to ~1.0 (Xdebug is no longer required).

4. Symfony Version Mismatch:

   • Symptom: Bundle fails to load or breaks the Profiler.
   • Fix: Tested with Symfony 4+. For Symfony 3, use ~0.9 (if available) or fork the bundle.

5. Performance in CI:

   • Symptom: Tests run slowly due to stack trace collection.
   • Fix: Disable in test environments by setting:

     # config/packages/sidus_doctrine_debug.yaml
     sidus_doctrine_debug:
         enabled: false
     

Debugging Tips

• Check Bundle Loading:

  php bin/console debug:container sidus_doctrine_debug
  

  • If missing, verify bundles.php or AppKernel.php.

• Enable Verbose Logging:

  php bin/console debug:config sidus_doctrine_debug
  

  • Look for errors in var/log/dev.log.

• Inspect Profiler Data:

  • The bundle adds data to the Profiler’s doctrine collector. Use:

    $profiler = $this->get('profiler');
    $data = $profiler->load('doctrine')->getData();
    

Extension Points

1. Custom Stack Trace Formatting:

   • Extend the DoctrineDebugDataCollector to modify how stack traces are displayed:

     // src/EventListener/CustomDoctrineDebugListener.php
     use Sidus\DoctrineDebugBundle\DataCollector\DoctrineDebugDataCollector;
     
     class CustomDoctrineDebugListener extends DoctrineDebugDataCollector
     {
         public function collect()
         {
             $traces = parent::collect();
             // Modify $traces['queries'] here (e.g., truncate, highlight files).
             return $traces;
         }
     }
     

2. Filtering Queries:

   • Exclude specific queries (e.g., migrations) by overriding the isQueryRelevant() method in the collector.

3. Adding Metadata:

   • Inject custom data (e.g., query execution time) by extending the bundle’s QueryData class.

Configuration Quirks

• No Runtime Config:

  • The bundle has no public configuration options (as of v1.0). All logic is hardcoded in the collector.

• Environment-Specific Enforcement:

  • The bundle auto-disables in prod, but explicitly set:

    # config/packages/dev/sidus_doctrine_debug.yaml
    sidus_doctrine_debug:
        enabled: true
    

    # config/packages/prod/sidus_doctrine_debug.yaml
    sidus_doctrine_debug:
        enabled: false
    

Advanced Use Cases

1. Query Annotations:

   • Use the stack trace to annotate queries in your codebase (e.g., mark // SLOW QUERY above the triggering method).

2. Automated Query Audits:

   • Write a script to parse Profiler data and flag queries with stack traces deeper than 3 levels (potential N+1).

3. Integration with Blackfire:

   • Use the stack trace to correlate Doctrine queries with Blackfire profiles for deeper performance analysis.

Note: For Laravel, consider forking this bundle to adapt it for Laravel’s ecosystem (e.g., using Laravel Debugbar instead of Symfony Profiler). Alternatively, use Doctrine’s built-in logging or Telescope for similar functionality.