Web Profiler Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require aureja/web-profiler-bundle "dev-master"
   

   • Ensure your project meets the PHP (>=5.5) and Symfony (>=2.7) requirements.

2. Register the Bundle: Add the bundle to AppKernel.php under dev/test environments:

   $bundles[] = new Aureja\Bundle\WebProfilerBundle\AurejaWebProfilerBundle();
   

3. Enable Profiling:

   • Clear cache: php bin/console cache:clear.
   • Access your app in a browser (e.g., http://localhost:8000/_profiler). The profiler toolbar should appear.

4. First Use Case:

   • Navigate to /_profiler to view ORM queries and detect duplicates.
   • Focus on the "ORM" tab to analyze query performance and duplicates.

Implementation Patterns

Core Workflows

1. Query Analysis:

   • Use the profiler toolbar to inspect executed queries under the "ORM" tab.
   • Sort queries by execution time or count to identify bottlenecks.

2. Duplicate Detection:

   • The bundle highlights duplicate queries (same SQL, parameters) with a visual indicator (e.g., color-coding or icons).
   • Click on duplicates to see all occurrences and their contexts (e.g., route, controller, line number).

3. Integration with Symfony Profiler:

   • Leverage existing Symfony Profiler features (e.g., timers, events) alongside ORM-specific data.
   • Example: Correlate slow queries with HTTP requests or Doctrine events.

4. Development Workflow:

   • Debugging: Use the profiler during local development to optimize queries before deploying.
   • CI/CD: Add a step to flag duplicate queries in automated tests (if extended via custom logic).

5. Custom Data Collection:

   • Extend the bundle by overriding templates or adding custom collectors (see Gotchas for details).
   • Example: Add query parameter logging for sensitive data masking.

Integration Tips

1. Doctrine Event Listeners:

   • Attach listeners to query or resultSet events to log custom metrics:

     $eventManager->addEventListener(
         Doctrine\ORM\Events::POST_FLUSH,
         function ($event) {
             // Log N+1 queries or other custom logic.
         }
     );
     

2. Toolbar Configuration:

   • Customize the toolbar position or visibility via Symfony’s profiler configuration:

     # config/packages/dev/aureja_web_profiler.yaml
     aureja_web_profiler:
         toolbar: true
         position: bottom  # 'top' or 'bottom'
     

3. Excluding Queries:

   • Filter out harmless queries (e.g., migrations) by whitelisting/blacklisting SQL patterns in a service:

     $profiler->setQueryFilter(function ($sql) {
         return !str_contains($sql, 'migration_');
     });
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Profiling adds overhead. Disable in production:

     if ($this->getEnvironment() !== 'dev') {
         return;
     }
     $bundles[] = new AurejaWebProfilerBundle();
     

   • Use --env=test for CI to avoid false positives.

2. Duplicate Query False Positives:

   • Identical SQL with different parameters (e.g., WHERE id = ?) may be flagged as duplicates.
   • Fix: Adjust the comparison logic in the bundle’s QueryCollector (extend Aureja\Bundle\WebProfilerBundle\DataCollector\QueryCollector).

3. Template Overrides:

   • The bundle uses Twig templates for the profiler UI. Override them in templates/bundles/aurejawebprofiler/ to customize output.
   • Tip: Clear cache after overriding templates.

4. Doctrine Version Mismatch:

   • The bundle targets Doctrine ORM ~2.5. For newer versions (e.g., 3.x), patch the QueryListener or fork the bundle.

5. Missing Data in Profiler:

   • If ORM data is empty, verify:
     • The bundle is registered in dev/test environments.
     • Doctrine’s event manager is active (check config/packages/doctrine.yaml).

Debugging Tips

1. Log Query Events:

   • Enable Doctrine logging to cross-reference with profiler data:

     # config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

2. Check Bundle Initialization:

   • Debug the AurejaWebProfilerBundle::build() method to ensure collectors are registered:

     dump($this->get('profiler')->getDataCollectors());
     

3. Query Comparison Logic:

   • Inspect the QueryCollector class to understand how duplicates are detected. Override the isDuplicate() method if needed:

     class CustomQueryCollector extends QueryCollector {
         public function isDuplicate(Query $query, array $queries) {
             // Custom logic here.
         }
     }
     

Extension Points

1. Custom Data Collectors:

   • Add new collectors by implementing DataCollectorInterface and registering them in the bundle’s Resources/config/services.yaml:

     services:
         app.custom_profiler:
             class: App\Profiler\CustomCollector
             tags: ['data_collector']
     

2. Query Annotations:

   • Annotate controllers/actions to log custom metadata:

     use Aureja\Bundle\WebProfilerBundle\Annotation\ProfileQuery;
     
     /**
      * @ProfileQuery("custom_label")
      */
     public function index() { ... }
     

3. Export Profiler Data:

   • Extend the bundle to export profiler data (e.g., JSON/CSV) for analysis:

     $profiler->exportData('/path/to/output.json');
     

4. Visual Indicators:

   • Customize the toolbar icon or add badges for critical queries (e.g., slow or duplicate):

     {# templates/bundles/aurejawebprofiler/toolbar.html.twig #}
     {% if hasDuplicateQueries %}
         <span class="badge badge-danger">Duplicates: {{ duplicateCount }}</span>
     {% endif %}