Debug Pack Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/debug-pack
   

   This installs the webprofilerbundle and stopwatch components, along with the debug-toolbar for Symfony applications.

2. Enable in config/bundles.php:

   return [
       // ...
       Symfony\Bundle\DebugBundle\DebugBundle::class => ['all' => true],
       Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true],
   ];
   

3. First Use Case:

   • Run your Laravel app in dev environment (APP_ENV=dev).
   • Access any route—you’ll see the Debug Toolbar at the bottom of the page.
   • Click the toolbar to inspect:
     • Request/response details.
     • Database queries (if using Doctrine).
     • Time spent in routes/controllers.
     • Exceptions and logs.

Implementation Patterns

Daily Workflows

1. Debugging Routes/Requests:

   • Use the Request tab to verify headers, POST data, and route parameters.
   • Compare expected vs. actual request data during API testing.

2. Performance Profiling:

   • The Time tab breaks down execution time by:
     • Controllers (App\Http\Controllers\*).
     • Middleware (App\Http\Middleware\*).
     • Database queries (if using Doctrine).
   • Identify bottlenecks by sorting by "Time" or "Calls."

3. Database Debugging:

   • The Doctrine tab lists all queries with:
     • Execution time.
     • SQL and parameters.
     • Row counts.
   • Useful for optimizing N+1 queries or slow joins.

4. Exception Tracking:

   • The Exceptions tab logs uncaught errors with:
     • Stack traces.
     • Variable dumps.
   • Reproduce bugs by filtering by exception type (e.g., Symfony\Component\HttpKernel\Exception\NotFoundHttpException).

5. Event Dispatching:

   • The Events tab lists dispatched events (e.g., Illuminate\Auth\Events\Registered) with payloads.
   • Verify event listeners are triggered as expected.

Integration Tips

• Laravel-Specific:
  • Pair with laravel-debugbar for deeper Laravel integration (e.g., Eloquent queries, Blade templates).
  • Use dd() or dump() in controllers—variables appear in the Variables tab.
• Custom Data Collection:
  • Extend the toolbar with custom panels (see WebProfilerBundle's DataCollector interface).
  • Example: Log custom metrics (e.g., third-party API calls) via:

    use Symfony\Component\HttpKernel\DataCollector\DataCollector;
    
    class CustomDataCollector implements DataCollector {
        public function collect(Request $request, Response $response, \Exception $exception = null) {
            // Add your data to $this->data.
        }
        public function getName() { return 'custom'; }
        public function getTemplate() { return '@WebProfiler/Collector/custom.html.twig'; }
    }
    

  • Register in config/packages/dev.php:

    web_profiler:
        collectors:
            custom: App\CustomDataCollector
    

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • The toolbar adds ~10–50ms per request. Disable in production (dev environment only).
   • Avoid using in CI/CD pipelines unless explicitly needed.

2. Doctrine-Only Database Tab:

   • The Doctrine tab only appears if you use Doctrine ORM. For raw PDO/Query Builder:
     • Use laravel-debugbar or log queries manually:

       DB::enableQueryLog();
       // ... run queries ...
       dd(DB::getQueryLog());
       

3. Caching Conflicts:

   • Clear cache after adding custom collectors:

     php artisan cache:clear
     php artisan config:clear
     

4. Toolbar Not Showing:

   • Ensure APP_ENV=dev and APP_DEBUG=true in .env.
   • Check config/bundles.php for correct bundle loading.
   • Verify no middleware (e.g., TrustProxies) blocks the toolbar’s headers.

5. CSRF Token Issues:

   • The toolbar may fail if CSRF protection is strict. Exclude its routes in VerifyCsrfToken middleware:

     protected $except = [
         '/_profiler*',
         '/_wdt*',
     ];
     

Debugging Tips

• Inspect Headers:

  • The toolbar shows response headers. Useful for debugging:
    • CORS issues (Access-Control-Allow-Origin).
    • Cache headers (Cache-Control).
  • Add custom headers in AppServiceProvider:

    public function boot() {
        header('X-Custom-Header: value');
    }
    

• Variable Dumping:

  • Use dump() or dd() in controllers—variables appear in the Variables tab.
  • For complex objects, use toArray() or json() to serialize:

    dump($user->toArray());
    

• Network Tab:

  • The Network tab (if enabled) shows HTTP requests made by the page (e.g., assets, APIs).
  • Filter by domain to debug third-party API calls.

Extension Points

1. Custom Profiler Data:

   • Implement DataCollector to add tabs (e.g., for queue jobs, cache hits).
   • Example: Log queue job processing time:

     class QueueDataCollector implements DataCollector {
         public function collect(Request $request, Response $response) {
             $this->data['jobs'] = [
                 'processed' => Queue::size(),
                 'failed' => FailedJob::count(),
             ];
         }
         // ... getName(), getTemplate() ...
     }
     

2. Override Templates:

   • Customize toolbar templates in resources/views/vendor/web-profiler/.
   • Example: Modify the Time tab to highlight slow queries:

     {# resources/views/vendor/web-profiler/collector/time.html.twig #}
     {% for event in events %}
         {% if event.duration > 1000 %} <!-- Highlight slow events -->
             <tr class="bg-red-100">
         {% endif %}
         <!-- ... rest of template ... -->
     {% endfor %}
     

3. Disable Specific Collectors:

   • Exclude collectors in config/packages/dev.php:

     web_profiler:
         collectors:
             # Disable the 'router' collector
             router: false