Laravel Debugbar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require fruitcake/laravel-debugbar --dev
   

   • Auto-discovery handles registration in Laravel 5.5+.

2. Enable Debug Mode: Set APP_DEBUG=true in .env to enable the debugbar automatically.

3. First Use Case:

   • Trigger a request (e.g., visit / or run php artisan tinker).
   • Observe the debugbar at the bottom of the page, showing default collectors like Time, Memory, Requests, and Logs.

Implementation Patterns

Core Workflows

1. Debugging Requests:

   • Use the Requests tab to inspect incoming requests, headers, and payloads.
   • Enable AJAX tracking in config/debugbar.php:

     'capture_ajax' => true,
     'ajax_handler_auto_show' => true,
     

   • View AJAX history via the folder icon (3rd from the right).

2. Performance Profiling:

   • Use start_measure()/stop_measure() or the Debugbar facade:

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

   • Alternatively, use helper functions:

     measure('query', function () {
         User::all();
     });
     

3. Logging Custom Data:

   • Add messages with PSR-3 levels:

     Debugbar::info('User loaded', ['id' => $user->id]);
     Debugbar::error(new \Exception('Failed to save'));
     

   • Use helpers for quick debugging:

     debug($variable); // Dumps to debugbar
     collect([1, 2, 3])->debug();
     

4. Job Debugging:

   • Enable job collection in config/debugbar.php:

     'collect_jobs' => true,
     

   • View processed jobs via the browse button (folder icon).

5. Console Debugging:

   • Manually enable debugbar in commands:

     $debugbar = app('debugbar');
     $debugbar->enable();
     // ... command logic ...
     

   • Access stored data via the browse button in the UI.

Integration Tips

1. Conditional Debugbar:

   • Disable for specific routes in config/debugbar.php:

     'except' => ['api/*', 'admin/*'],
     

   • Dynamically enable/disable:

     if (auth()->check()) {
         debugbar()->disable();
     }
     

2. Custom Collectors:

   • Add third-party collectors (e.g., maximebf/debugbar-extensions):

     Debugbar::addCollector(new \DebugBar\DataCollector\TimeDataCollector());
     

   • Create a custom collector by extending DebugBar\DataCollector\BaseCollector.

3. Editor Integration:

   • Configure remote/local path mappings for Docker/Homestead:

     'remote_sites_path' => '/home/vagrant/Code',
     'local_sites_path'  => '/Users/you/Projects',
     

   • Set your preferred editor (e.g., DEBUGBAR_EDITOR=vscode).

4. Twig Integration:

   • Register extensions in config/twigbridge.php:

     'extensions' => [
         Fruitcake\LaravelDebugbar\Twig\Extension\Debug::class,
         Fruitcake\LaravelDebugbar\Twig\Extension\Dump::class,
     ],
     

   • Use in templates:

     {{ dump(user) }}
     

5. Storage Configuration:

   • Switch to Redis for shared storage (e.g., in queues):

     'storage' => [
         'driver' => 'redis',
         'connection' => 'cache',
     ],
     

   • Restrict access via a callback:

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

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Disable debugbar in production (APP_DEBUG=false).
   • Avoid enabling collect_jobs in high-traffic queues; it logs every job execution.

2. Storage Leaks:

   • Never enable storage.open in shared environments (e.g., staging/production).
   • Clear storage manually if needed:

     php artisan debugbar:clear
     

3. AJAX Conflicts:

   • Disable capture_ajax if AJAX requests fail or time out:

     'capture_ajax' => false,
     

   • Ensure AJAX requests include X-Requested-With: XMLHttpRequest or Accept: application/json.

4. Editor Links:

   • Remote path mappings may break if local/remote paths change. Test links after setup.

5. Collector Conflicts:

   • Some collectors (e.g., CacheCollector) may require additional setup (e.g., cache:table migrations).

Debugging Tips

1. Missing Debugbar:

   • Verify APP_DEBUG=true and no except rules block the route.
   • Check for JavaScript errors (debugbar relies on frontend JS).

2. Empty Tabs:

   • Enable hide_empty_tabs to hide collectors with no data:

     'hide_empty_tabs' => true,
     

   • Manually add data to collectors (e.g., Debugbar::addMessage()).

3. Storage Issues:

   • Ensure the storage/debugbar directory is writable:

     mkdir -p storage/debugbar && chmod -R 775 storage/debugbar
     

   • For Redis, verify the connection is configured in config/database.php.

4. Facade Not Found:

   • Register the facade alias in AppServiceProvider:

     \Illuminate\Foundation\AliasLoader::getInstance()->alias('Debugbar', \Fruitcake\LaravelDebugbar\Facades\Debugbar::class);
     

5. Octane Compatibility:

   • Debugbar works with Octane out-of-the-box, but avoid enabling it in production workers.

Extension Points

1. Custom Collectors:

   • Extend DebugBar\DataCollector\BaseCollector and register via:

     Debugbar::addCollector(new MyCustomCollector());
     

2. Middleware Integration:

   • Add debugbar data in middleware:

     public function handle($request, Closure $next) {
         Debugbar::info('Middleware executed', ['user' => auth()->user()]);
         return $next($request);
     }
     

3. Event Listeners:

   • Log events to debugbar:

     public function handle(JobProcessed $event) {
         Debugbar::addMessage('Job processed', ['job' => $event->job]);
     }
     

4. Theme Customization:

   • Override CSS via public/css/debugbar.css or use the DEBUGBAR_THEME env var:

     DEBUGBAR_THEME=dark
     

5. ServerTiming Headers:

   • Enable for Chrome DevTools:

     'add_ajax_timing' => true,
     

   • Manually add timing headers:

     header('Server-Timing: my-metric;dur=123');