Laravel Debugbar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require fruitcake/laravel-debugbar
   

   Publish the config file:

   php artisan vendor:publish --provider="Fruitcake\LaravelDebugbar\DebugbarServiceProvider"
   

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

3. First Use Case: Visit any route in your Laravel app. The debug bar will appear at the bottom of the page, displaying default collectors (queries, messages, timeline, etc.).

Implementation Patterns

Core Workflows

1. Debugging Queries:

   • Enable the db collector in config/debugbar.php to inspect SQL queries, execution time, and parameters.
   • Use debugbar()->addCollector() dynamically to enable collectors for specific routes or middleware.

2. Logging Messages:

   • Replace dd() or dump() with debug() for cleaner output in the Messages tab.
   • Use the Debugbar facade for structured logging:

     Debugbar::info('User logged in', ['user_id' => $user->id]);
     

3. Performance Profiling:

   • Use Debugbar::startMeasure() and Debugbar::stopMeasure() to track custom operations:

     Debugbar::startMeasure('render', 'Rendering view');
     // ... view logic ...
     Debugbar::stopMeasure('render');
     

   • Leverage the Timeline collector to visualize app boot time and request lifecycle.

4. Exception Handling:

   • Log exceptions automatically with the exceptions collector.
   • Manually add throwables:

     try { ... } catch (\Exception $e) {
         Debugbar::addThrowable($e);
     }
     

5. Conditional Debugging:

   • Disable collectors in production via config:

     'collectors' => [
         'db' => env('APP_DEBUG') ? true : false,
     ]
     

   • Enable/disable runtime:

     if (request()->ip() === '127.0.0.1') {
         debugbar()->enable();
     }
     

Integration Tips

• Middleware: Enable debugbar for specific routes:

  public function handle($request, Closure $next) {
      if ($request->ip() === '127.0.0.1') {
          debugbar()->enable();
      }
      return $next($request);
  }
  

• Livewire: The livewire collector auto-detects Livewire components and logs their lifecycle.

• Twig: Replace {{ dump(var) }} with {{ debug(var) }} for formatted output in templates.

• Jobs: Enable debugbar.collect_jobs in .env to track dispatched jobs (requires jobs collector).

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Disabled collectors by default in production (APP_DEBUG=false).
   • Use soft_limit and hard_limit in db collector to cap query logging:

     'db' => [
         'soft_limit' => 50,  // Stop capturing params after 50 queries
         'hard_limit' => 200, // Ignore queries after 200
     ]
     

2. Storage Risks:

   • Never enable debugbar.storage.open in production—it exposes request history to all users.
   • Restrict access via IP or middleware:

     'storage' => [
         'open' => function ($request) {
             return $request->ip() === '127.0.0.1';
         },
     ]
     

3. Query Backtrace:

   • Exclude vendor paths to avoid clutter:

     'db' => [
         'backtrace_exclude_paths' => [
             'vendor/laravel/',
             'vendor/fruitcake/',
         ],
     ]
     

4. Twig Conflicts:

   • Ensure rcrowe/TwigBridge is version 0.6.x for Debugbar’s Twig extensions.
   • Clear Twig cache after adding extensions:

     php artisan twig:clear
     

5. Livewire Compatibility:

   • Debugbar may not work with Livewire’s Turbo mode. Disable Turbo or use debugbar()->disable() in Livewire components.

Debugging Tips

• Disable Collectors Temporarily: Override config in bootstrap/app.php:

  $debugbar = app('debugbar');
  $debugbar->disableCollector('db'); // Disable queries
  

• Custom Collectors: Extend existing collectors (e.g., MessagesCollector) or create new ones:

  use DebugBar\DataCollector\DataCollector;
  class MyCollector extends DataCollector {
      public function collect() {
          $this->data['custom_data'] = 'value';
      }
  }
  Debugbar::addCollector(new MyCollector());
  

• Query EXPLAIN: Enable on-demand EXPLAIN for slow queries:

  'db' => [
      'explain' => [
          'enabled' => true,
      ],
  ]
  

  Click the "EXPLAIN" button in the Debugbar UI.

• Memory Leaks: Monitor memory usage with the memory collector. High spikes may indicate:

  • Unclosed database connections.
  • Large query results not paginated.
  • Cached data growing uncontrollably.

Configuration Quirks

• Environment Variables: Override config via .env:

  DEBUGBAR_COLLECTORS="db,time,messages"
  DEBUGBAR_DB_SOFT_LIMIT=20
  

• Middleware Order: Place DebugbarMiddleware after TrustProxies and before VerifyCsrfToken to avoid IP mismatches.

• Livewire Debugging: Use debugbar()->disable() in AppServiceProvider for Livewire-only routes:

  if (request()->route()->getName() === 'livewire.route') {
      debugbar()->disable();
  }
  

• CSRF Token: Debugbar may interfere with CSRF verification. Exclude its routes in VerifyCsrfToken:

  protected $except = [
      'debugbar/*',
  ];