Web Profiler Bundle Laravel Package

Getting Started

Minimal Steps to Enable

1. Installation:

   composer require symfony/web-profiler-bundle
   

   For Laravel (Symfony 5+ compatible), add to config/app.php under extra.bundles (if using Symfony components):

   'bundles' => [
       // ...
       Symfony\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
   ],
   

2. Enable Debug Mode: Set APP_DEBUG=true in .env:

   APP_DEBUG=true
   APP_ENV=local
   

3. First Use Case:

   • Trigger a request (e.g., php artisan serve + visit /).
   • Observe the Debug Toolbar at the bottom of the page (if using Symfony’s built-in server).
   • For Laravel, use the Laravel Debugbar (alternative) or integrate Symfony’s profiler via symfony/http-kernel.
   • Access the profiler at /_profiler/ (e.g., http://localhost:8000/_profiler/).
   • Inspect default panels: Requests, Time, Router, Doctrine (if using DBAL/ORM).

Implementation Patterns

Core Workflows in Laravel Context

1. Debugging HTTP Requests:

   • Use the Requests panel to compare current vs. previous requests (e.g., after API changes).
   • Filter by status code (e.g., 500) to isolate errors.
   • Example: Debug a failed POST /api/login by inspecting headers, body, and response.

2. Performance Profiling:

   • Timeline panel: Visualize execution flow (e.g., middleware → controller → service).
   • Sort by duration to find slow components (e.g., Eloquent queries, external API calls).
   • Example: Click a query in Doctrine to see raw SQL and execution time.

3. State Inspection:

   • Response panel: Inspect headers, cookies, or rendered JSON/XML.
   • Exceptions panel: Review stack traces with request/response context.
   • Example: Debug a 404 by checking the Router panel for missing routes.

4. Custom Data Collection (Laravel Integration):

   • Create a DataCollector to log Laravel-specific metrics (e.g., queue jobs, cache hits):

     // app/Collectors/CustomCollector.php
     use Symfony\Component\HttpKernel\DataCollector\DataCollector;
     use Illuminate\Support\Facades\Cache;
     
     class CustomCollector extends DataCollector {
         public function collect($request, $response) {
             $this->data['cache_hits'] = Cache::stats()['hits'] ?? 0;
             return $this->data;
         }
     
         public function getName() { return 'laravel_cache'; }
     }
     

   • Register in config/profiler.php (if using Symfony’s profiler):

     'collectors' => [
         'laravel_cache' => App\Collectors\CustomCollector::class,
     ],
     

5. Integration with Laravel Debugbar:

   • Use Laravel Debugbar (barryvdh/laravel-debugbar) for Laravel-native profiling, then extend with Symfony’s profiler for advanced features (e.g., Doctrine, Twig).
   • Example: Combine Debugbar’s Messages with Symfony’s Events panel.

Gotchas and Tips

Pitfalls

1. Toolbar Not Showing in Laravel:

   • Symfony’s profiler requires a Symfony kernel. For Laravel, use:
     • Option 1: Wrap Laravel in Symfony’s HttpKernel (advanced).
     • Option 2: Use Laravel Debugbar (barryvdh/laravel-debugbar) as a drop-in alternative.
     • Option 3: Proxy requests through Symfony (e.g., symfony/web-server-bundle).

2. Performance Overhead:

   • Disable in production (APP_DEBUG=false) and CI environments.
   • For local testing, use --env=testing to avoid profiler noise.

3. Doctrine Queries Missing:

   • Ensure doctrine/dbal or doctrine/orm is installed and configured.
   • Enable SQL logging in config/database.php:

     'logging' => true,
     

4. Collector Conflicts:

   • Avoid naming custom collectors after built-in ones (e.g., time, router).
   • Clear cache after adding new collectors:

     php artisan cache:clear
     

Debugging Tips

1. Inspecting Blade Templates:

   • Use the Twig panel (if using Symfony’s Twig) to debug template rendering times.
   • For Laravel Blade, use Debugbar’s Blade panel instead.

2. Event Debugging:

   • The Events panel lists all dispatched events (e.g., Laravel’s Illuminate\Events\Dispatcher).
   • Useful for debugging service providers or listeners.

3. Memory Leaks:

   • Monitor the Memory panel across requests to spot growing memory usage.
   • Compare with memory_get_usage() in PHP for granular tracking.

4. Custom Data Visualization:

   • Override Symfony’s profiler templates in resources/views/vendor/web-profiler/ (if using Laravel’s view system).
   • Example: Add a chart for custom collector data using Blade.

Configuration Quirks

1. Disabling Specific Collectors:

   // config/profiler.php
   'collectors' => [
       'Symfony\Bundle\WebServerBundle\DataCollector\WebServerCollector' => false,
   ],
   

2. Profiler in API Tests:

   • Enable the profiler in PHPUnit tests:

     use Symfony\Component\HttpKernel\Profiler\Profiler;
     
     public function testApi() {
         $profiler = new Profiler();
         $profiler->enable();
         $response = $this->get('/api/endpoint');
         // Assertions using profiler data...
     }
     

3. Laravel-Specific Workarounds:

   • For Laravel 8+, use symfony/http-kernel to integrate Symfony’s profiler:

     composer require symfony/http-kernel
     

   • Create a middleware to wrap requests:

     // app/Http/Middleware/ProfilerMiddleware.php
     use Symfony\Component\HttpKernel\HttpKernelInterface;
     
     public function handle($request, Closure $next) {
         $kernel = new HttpKernel();
         $response = $kernel->handle($request, HttpKernelInterface::MAIN_REQUEST);
         return $response;
     }
     

4. Security Note:

   • Never expose /_profiler/ in production. Use firewall rules to block access:

     // routes/web.php
     Route::middleware(['web', 'profiler'])->group(function () {
         // Profiler routes
     });