Doctrine Hydration Profiler Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require debesha/doctrine-hydration-profiler-bundle
   

   Add the bundle to config/bundles.php (Symfony 5.4+ auto-discovers it, but explicit declaration ensures compatibility):

   return [
       // ...
       Debesha\DoctrineProfileExtraBundle\DoctrineProfileExtraBundle::class => ['all' => true],
   ];
   

2. Enable Profiler: Ensure Symfony's profiler is enabled in config/packages/dev/profiler.yaml:

   framework:
       profiler: { only_exceptions: false }
   

3. First Use Case:

   • Trigger a request (e.g., php bin/console server:run).
   • Navigate to /_profiler and inspect the "Doctrine Hydration" tab.
   • Observe hydration metrics (time, entity count, hydration mode) for all Doctrine queries.

Key Starting Points

• Profiler Tab: /_profiler/{token}?panel=doctrine_hydration
• Configuration: config/packages/dev/doctrine_profile_extra.yaml (if needed).
• Doctrine Events: The bundle hooks into loadClassMetadata and postLoad events.

Implementation Patterns

Common Workflows

1. Debugging Slow Queries:

   • Use the profiler to identify hydration bottlenecks (e.g., HYDRATE_ARRAY vs. HYDRATE_OBJECT).
   • Example: A query hydrating 1000 entities in HYDRATE_ARRAY may take 500ms—switching to HYDRATE_OBJECT could reduce this to 100ms.

2. Performance Profiling:

   • Compare hydration times across environments (dev/staging/prod).
   • Correlate hydration time with query complexity (e.g., joins, lazy loading).

3. Integration with Custom Logic:

   • Extend the profiler data via event subscribers (see DoctrineHydrationEvent).
   • Example: Log hydration metrics to a monitoring tool:

     use Debesha\DoctrineProfileExtraBundle\Event\DoctrineHydrationEvent;
     
     public function onHydration(DoctrineHydrationEvent $event) {
         if ($event->getDuration() > 100) { // ms
             $this->monitoringClient->logWarning($event->getEntityClass(), $event->getDuration());
         }
     }
     

4. Conditional Profiling:

   • Disable hydration profiling in production by overriding the bundle’s enabled config:

     doctrine_profile_extra:
         enabled: false  # Disable in prod
     

Integration Tips

• Doctrine DQL: Use HYDRATE_SCALAR for simple queries to avoid hydration overhead.
• Symfony Cache: Clear cache (php bin/console cache:clear) after enabling the bundle.
• Custom Hydrators: If using custom hydrators (e.g., ResultSetMapping), ensure they’re compatible with the profiler’s instrumentation.
• APIs: For GraphQL/API Platform, use the profiler to validate hydration strategies for nested data fetching.

Gotchas and Tips

Pitfalls

1. Overhead in Development:

   • The profiler adds minimal overhead (~1-5ms per hydration), but avoid enabling it in performance-critical tests.
   • Fix: Disable via config or environment checks:

     doctrine_profile_extra:
         enabled: '%kernel.debug%'  # Only in dev
     

2. Missing Data:

   • If the "Doctrine Hydration" tab is empty:
     • Verify Doctrine events are fired (check postLoad listeners).
     • Ensure the bundle is loaded (debug config/bundles.php).
     • Debug: Add DoctrineProfileExtraBundle to config/bundles.php explicitly.

3. EntityManager-Specific Data:

   • The profiler tracks hydration per EntityManager. For multi-EM setups, data may be split across tabs.

4. Hydration Modes:

   • HYDRATE_ARRAY and HYDRATE_SCALAR are profiled, but HYDRATE_OBJECT may show higher times due to entity lifecycle callbacks.

Debugging Tips

• Log Events: Enable debug logging for the bundle:

  monolog:
      handlers:
          main:
              level: debug
              channels: ["doctrine"]
  

• Event Subscribers: Use DoctrineHydrationEvent to inspect raw data:

  $event->getHydrationData(); // Array of all hydration records.
  

• Doctrine Profiler: Cross-reference with Symfony’s built-in Doctrine profiler (/profiler/{token}?panel=doctrine) for query-level insights.

Extension Points

1. Custom Data Collectors:

   • Extend HydrationDataCollector to add custom metrics (e.g., memory usage):

     use Debesha\DoctrineProfileExtraBundle\DataCollector\HydrationDataCollector;
     
     class CustomHydrationDataCollector extends HydrationDataCollector {
         public function collect($data) {
             $data['memory_usage'] = memory_get_usage();
             return parent::collect($data);
         }
     }
     

   • Register via dependency injection.

2. Event Listeners:

   • Subscribe to DoctrineHydrationEvent to modify or enrich hydration data:

     $event->addMetadata('custom_tag', 'value');
     

3. Template Overrides:

   • Customize the profiler tab by overriding the Twig template:

     templates/bundles/DoctrineProfileExtra/doctrine_hydration.html.twig
     

Configuration Quirks

• Doctrine Version: Tested with ORM ^2.19|^3.0. For older versions, check compatibility.
• Proxy Classes: Hydration of proxied entities (e.g., Proxy\__CG__\User) may show as separate entries.
• Lazy Loading: Hydration time for lazy-loaded associations is included in the parent entity’s metrics.