Web Profiler Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require symfony/web-profiler-bundle
   

   Add to config/app.php under providers (Laravel 8+):

   Symfony\Component\HttpKernel\Bundle\BundleInterface::class => [
       Symfony\WebProfilerBundle\WebProfilerBundle::class,
   ],
   

2. Enable Debug Mode: Set APP_DEBUG=true in .env and ensure APP_ENV=local:

   APP_DEBUG=true
   APP_ENV=local
   

3. First Use Case:

   • Trigger a request (e.g., visit / or run php artisan serve).
   • Observe the Debug Toolbar at the bottom of the page (if using Symfony’s built-in server or a compatible web server like Apache/Nginx with X-Powered-By: Symfony).
   • Click the toolbar to open the Profiler (/_profiler/).
   • Inspect default panels like Requests, Time, Router, and Doctrine (if using Laravel’s Eloquent or Doctrine).

Implementation Patterns

Core Workflows

1. Debugging HTTP Requests:

   • Use the Requests panel to compare current vs. previous requests (e.g., after API changes).
   • Filter by URL, method, or status code to isolate issues like 500 errors or slow responses.
   • Example: Debug a failed POST request by inspecting headers, body, and response.

2. Performance Profiling:

   • Timeline panel visualizes execution flow (e.g., middleware → controller → service → DB).
   • Sort by duration to identify bottlenecks (e.g., slow Eloquent queries, external API calls).
   • Example: Click a query in Doctrine to see its SQL and execution time, then optimize with ->select() or caching.

3. State Inspection:

   • Response panel: Inspect headers, cookies, or rendered content (e.g., debug JSON API responses).
   • Exceptions panel: Review uncaught errors with stack traces and context (e.g., debug QueryException in a controller).
   • Variables panel: Dump any variable from the request lifecycle (e.g., debug a Request object in middleware).

4. Custom Data Collection:

   • 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 $request, Response $response, \Throwable $exception = null) {
             $this->data['cache_hits'] = Cache::stats()['hits'] ?? 0;
             return $this->data;
         }
     
         public function getName() { return 'custom'; }
     }
     

   • Register in config/profiler.php (create if missing):

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

5. Integration with Laravel Features:

   • Middleware Debugging: Use the Events panel to trace middleware execution order (e.g., debug auth:api or throttle).
   • Queue Debugging: Log dispatched jobs in a custom collector and correlate with the Time panel.
   • Blade Debugging: Inspect Twig-like Blade templates via the Twig panel (if using Laravel’s Blade compiler).

6. Testing Workflows:

   • Use Profiler::enable() in PHPUnit tests to capture profiler data:

     use Symfony\Component\HttpKernel\Profiler\Profiler;
     use Illuminate\Foundation\Testing\TestCase;
     
     class FeatureTest extends TestCase {
         protected function setUp(): void {
             parent::setUp();
             $profiler = app(Profiler::class);
             $profiler->enable();
         }
     
         public function testApiEndpoint() {
             $response = $this->get('/api/users');
             $this->assertEquals(200, $response->status());
             // Assert profiler data (e.g., query count)
             $this->assertEquals(1, $profiler->getCollector('db')->getQueryCount());
         }
     }
     

Gotchas and Tips

Pitfalls

1. Debug Toolbar Not Showing:

   • Ensure APP_DEBUG=true and APP_ENV=local.
   • Clear Laravel cache: php artisan cache:clear and php artisan view:clear.
   • Check for middleware blocking the toolbar (e.g., CORS or security middleware). Exclude /_profiler/* in production:

     // app/Http/Middleware/TrustProxies.php
     protected $proxies = TrustedProxy::IP_ADDRESSES | '*'; // Allow profiler IPs
     

   • For Nginx/Apache, ensure X-Powered-By: Symfony header is present (add to .htaccess or nginx.conf):

     Header set X-Powered-By "Symfony"
     

2. Performance Overhead:

   • The profiler adds ~10-30% overhead in development. Disable in CI/staging:

     APP_DEBUG=false
     

   • Use --env=testing for tests to avoid profiler noise.

3. Doctrine/Eloquent Queries Missing:

   • Ensure doctrine/dbal or laravel/framework (for Eloquent) is installed.
   • For custom repositories, enable query logging in config/database.php:

     'logging' => true,
     'logging_query' => true,
     

   • If using Eloquent, install symfony/var-dumper for better query inspection:

     composer require symfony/var-dumper
     

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.

5. Profiler in API Tests:

   • The profiler may interfere with API tests (e.g., HttpTests). Disable it in phpunit.xml:

     <env name="APP_DEBUG" value="false"/>
     

Debugging Tips

1. Inspecting Blade/Twig Rendering:

   • Use the Twig panel to see template hierarchy and timing for each section.
   • Click a template to debug variable dumps (e.g., debug a @foreach loop in Blade).

2. Event Dispatcher Debugging:

   • The Events panel lists all dispatched events with their listeners and execution order.
   • Useful for debugging middleware or event subscribers (e.g., Illuminate\Events\Dispatcher).

3. Memory Leaks:

   • Monitor the Memory panel across requests to spot growing memory usage.
   • Compare with memory_get_peak_usage() in PHP for granular tracking.
   • Example: Debug a memory leak in a loop by profiling a controller action.

4. Custom Data Visualization:

   • Extend the profiler UI by overriding templates in resources/views/vendor/web-profiler/ (Laravel 8+).
   • Example: Add a chart for your custom collector’s data using Blade.

5. Profiler in Queues/Jobs:

   • The profiler works for queued jobs if you enable it in the job’s handle method:

     use Symfony\Component\HttpKernel\Profiler\Profiler;
     
     public function handle() {
         $profiler = app(Profiler::class);
         $profiler->enable();
         // Job logic...
     }
     

   • View job data via /_profiler/{token}/jobs.

Configuration Quirks

1. Disabling Specific Collectors:

   // config/profiler.php
   'enabled_collectors' => [
       'time', 'memory', 'exceptions', 'logger', 'request', 'router',
       // Exclude 'doctrine' if not using DBAL/ORM
   ],
   

2. Profiler in Subrequests:

   • The profiler works for subrequests (e.g., from HttpClient or Cache::remember), but data is scoped to the parent request.
   • Use Profiler::enable() explicitly for isolated subrequests.

3. Production-Like Debugging:

   • Use APP_ENV=production with APP_DEBUG=true to test production configurations without toolbar noise.
   • Access profiler via /_profiler/ (disable in app/Http/Kernel.php if needed):

     protected $middlewareGroups = [
         'web' => [
             // ...
             \Symfony\Component\HttpKernel\Middleware\ProfilerMiddleware::class,
         ],
     ];
     

4. Laravel-Specific Adjustments:

   • Route Caching: Disable route caching in bootstrap/app.php if profiler isn’t working:

     $app->withRouting(
         $app->router()->cache(function () { return false; }),
     );
     

   • Service Provider Order: Ensure WebProfilerBundle