Laravel Debugbar Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require barryvdh/laravel-debugbar --dev
   

   Add to config/app.php under providers:

   Barryvdh\Debugbar\ServiceProvider::class,
   

   Publish config (optional):

   php artisan vendor:publish --provider="Barryvdh\Debugbar\ServiceProvider"
   

2. Enable Debug Mode: Set APP_DEBUG=true in .env or enable via code:

   debugbar()->enable();
   

3. First Use Case: Trigger a debug message in a controller:

   debug('User ID:', auth()->id());
   

   View the debug bar at the bottom of the page.

Implementation Patterns

Core Workflows

1. Debugging Queries:

   • Enable db collector in config/debugbar.php:

     'collectors' => ['db' => true],
     

   • Use explain for slow queries:

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

   • Exclude vendor paths to reduce noise:

     'exclude_paths' => ['vendor/laravel/framework/src/Illuminate/Session'],
     

2. Timing Critical Sections:

   start_measure('render', 'Time to render view');
   // ... logic ...
   stop_measure('render');
   

   Or inline:

   measure('API call', function() {
       $response = Http::get('https://api.example.com');
   });
   

3. Exception Handling:

   try {
       // Risky code
   } catch (\Exception $e) {
       Debugbar::addThrowable($e);
   }
   

4. Conditional Debugging:

   if (app()->environment('local')) {
       debugbar()->enable();
   }
   

Integration Tips

• Livewire: Enable livewire collector for component debugging.
• Queue Jobs: Set debugbar.collect_jobs=true in .env to track dispatched jobs.
• Twig: Replace dump() with debug() in templates for cleaner output.
• Console Commands: Enable debugbar manually:

  debugbar()->enable();
  debug('Command executed');
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Disable unused collectors (e.g., events, cache) in production-like environments.
   • Use soft_limit and hard_limit for queries to avoid memory bloat:

     'db' => ['soft_limit' => 50, 'hard_limit' => 200],
     

2. Storage Risks:

   • Never enable debugbar.storage.open in shared/staging environments. Use IP whitelisting:

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

3. Backtrace Exclusions:

   • Exclude paths from backtraces to reduce noise:

     'backtrace_exclude_paths' => [
         'vendor/',
         'storage/',
     ],
     

4. Twig Conflicts:

   • Ensure rcrowe/TwigBridge is compatible with your Laravel version (tested with 0.6.x).

Debugging Tips

• Query Hints: Enable hints to catch common SQL mistakes:

  'db' => ['hints' => true],
  

• Copy Queries: Use the clipboard button to quickly test queries in your DB client.
• Timeline: Add queries to the timeline for visual performance analysis:

  'db' => ['timeline' => true],
  

Extension Points

1. Custom Collectors:

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

   Or via container:

   app('debugbar')->addCollector(new \DebugBar\DataCollector\MyCustomCollector());
   

2. Override Default Collectors: Bind your collector in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           \DebugBar\DataCollector\DbCollector::class,
           \App\Debugbar\CustomDbCollector::class
       );
   }
   

3. Disable Collectors Dynamically:

   debugbar()->disableCollector('db'); // Disable queries
   debugbar()->enableCollector('events'); // Enable events
   

Pro Tips

• Environment-Specific Config: Use config/debugbar.php to toggle collectors per environment:

  'collectors' => [
      'db' => app()->environment('local'),
      'events' => app()->environment('staging'),
  ],
  

• Livewire Component Debugging: Enable livewire collector and use debug() in component methods to inspect props/state.
• Memory Profiling: Combine memory collector with soft_limit to track memory spikes:

  'collectors' => ['memory' => true],
  'options' => ['memory' => ['threshold' => 1024]], // MB
  

```markdown
### Debugging Common Issues
1. **Debugbar Not Showing**:
   - Verify `APP_DEBUG=true` in `.env`.
   - Check for middleware blocking the debugbar (e.g., `TrustedProxies`).
   - Ensure no JavaScript errors prevent the debugbar from rendering.

2. **Queries Missing**:
   - Confirm `db` collector is enabled.
   - Check `exclude_paths` isn’t filtering out your queries.
   - For Eloquent, ensure you’re not using `->toSql()` directly (use `debug()` instead).

3. **Performance Impact**:
   - Disable collectors in CI/CD pipelines:
     ```php
     if (app()->runningUnitTests()) {
         debugbar()->disable();
     }
     ```
   - Use `slow_threshold` to ignore fast queries:
     ```php
     'db' => ['slow_threshold' => 50], // ms
     ```

4. **Storage Corruption**:
   - Clear storage manually if requests disappear:
     ```bash
     php artisan debugbar:clear
     ```
   - Avoid enabling storage in shared environments.

### Advanced Usage
- **Custom Data Formatters**:
  Extend `\DebugBar\DataFormatter\DataFormatter` to handle your app’s models:
  ```php
  class CustomDataFormatter extends DataFormatter
  {
      public function format($data)
      {
          if ($data instanceof \App\Models\User) {
              return $data->toArray();
          }
          return parent::format($data);
      }
  }

Bind it in AppServiceProvider:

$this->app->bind(
    \DebugBar\DataFormatter\DataFormatter::class,
    \App\Debugbar\CustomDataFormatter::class
);

• Headless Mode (APIs): Capture debug data without rendering the bar:

  debugbar()->disableRenderer();
  debug('API request data');
  

  Access data via debugbar()->getData().

• Testing: Use Debugbar::disable() in phpunit.xml:

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

  Or mock the service provider in tests.