Getting Started

Minimal Setup

Installation: Add the package via Composer in a Laravel project (if using Symfony components):
```
composer require symfony/debug-bundle
```
For Laravel, manually register the bundle in config/app.php under extra.bundles (if using Symfony’s HttpKernel):
```
'bundles' => [
    // ...
    Symfony\Bundle\DebugBundle\DebugBundle::class => ['all' => true],
],
```
First Use Case:
- Toolbar Activation: Access /_profiler or /_error in development to see the Symfony Profiler toolbar.
- CLI Debugging: Run php bin/console debug:container to inspect service containers.
- VarDumper: Use dump() or dd() (via symfony/var-dumper) in controllers or commands for rich variable inspection.
Where to Look First:
- Toolbar: /_profiler for request/response data, exceptions, and SQL queries.
- CLI Commands: debug:container, debug:router, debug:event-dispatcher.
- Configuration: config/packages/dev/debug.yaml (Symfony) or config/debug.php (Laravel) to toggle features.

Implementation Patterns

Core Workflows

Debugging HTTP Requests:
- Use the toolbar to inspect:
  - Request headers, body, and cookies.
  - Response data, status codes, and headers.
  - Exception traces and stack dumps.
- Laravel Integration: Override the toolbar route in routes/web.php:
```
Route::get('/debug', [\Symfony\Bundle\DebugBundle\Controller\ProfilerController::class, 'profiler']);
```

CLI Debugging:

Service Inspection:

php artisan debug:container --show-private

Route Debugging:
```
php artisan debug:router
```
Event Listeners:
```
php artisan debug:event-dispatcher
```

VarDumper Integration:
- Replace var_dump() with dump() or dd() (via symfony/var-dumper):
```
use Symfony\Component\VarDumper\VarDumper;

VarDumper::dump($user); // Pretty-printed output
```
- Custom Dumpers: Extend VarDumper\Dumper\AbstractDumper for domain-specific objects.
Monolog Integration:
- Centralize logs and debug dumps via ServerLogCommand:
```
php artisan debug:server-log
```
- Configure log levels in config/packages/monolog.yaml:
```
handlers:
    main:
        level: debug
```
Environment-Specific Debugging:
- Enable/disable features via .env:
```
APP_DEBUG=true
SYMFONY_DEBUG_TOOLBAR=true
```
- Laravel: Use config('debug') to conditionally load the bundle.

Integration Tips

Laravel-Symfony Hybrid Apps:

Use Symfony\Component\HttpKernel\HttpKernelInterface for Symfony components while keeping Laravel’s routing.

Example: Wrap Laravel’s Kernel in Symfony’s HttpKernel:

use Symfony\Component\HttpKernel\Kernel as SymfonyKernel;

class AppKernel extends SymfonyKernel {
    public function __construct($environment, $debug) {
        parent::__construct($environment, $debug);
        $this->registerBundles();
    }
}

Custom Data Collectors:

Extend Symfony\Component\HttpKernel\DataCollector\DataCollector to add app-specific metrics (e.g., cache hits, queue jobs).

Example:

class CacheCollector extends DataCollector {
    public function collect(Request $request, \Symfony\Component\HttpKernel\HttpKernelInterface $kernel, Request $masterRequest) {
        $this->data['cache_hits'] = Cache::stats()['hits'];
    }
}

Debugging Queues/Jobs:
- Use the toolbar to inspect job payloads and exceptions.
- For Laravel Queues, pair with symfony/messenger and enable debug mode:
```
# config/packages/messenger.yaml
messenger:
    transports:
        async: { dsn: '%env(MESSENGER_TRANSPORT_DSN)%', options: { debug: true } }
```

Gotchas and Tips

Pitfalls

Performance Overhead:
- Issue: The toolbar and data collectors add ~10–15% overhead in development. Disabling them in production is critical.
- Fix: Use environment checks:
```
if (!$this->container->getParameter('kernel.debug')) {
    return;
}
```
Toolbar in Production:
- Issue: Accidental exposure of /_profiler or /_error in production can leak sensitive data.
- Fix:
  - Disable in config/packages/debug.yaml:
```
framework:
    router:
        debug: '%kernel.debug%'
```
  - Use Laravel’s middleware to block routes:
```
Route::middleware(['web', 'debug'])->group(function () {
    // Debug routes only
});
```

CLI Command Conflicts:

Issue: Namespace collisions with Laravel’s artisan commands (e.g., debug:container vs. laravel-debugbar).

Fix: Alias Symfony commands in artisan:

// In AppServiceProvider@boot()
$this->app['artisan']->extend(function ($artisan) {
    $artisan->add(new \Symfony\Bundle\DebugBundle\Command\DebugCommand());
});

VarDumper in Production:
- Issue: dd() or dump() calls can halt execution unexpectedly.
- Fix: Wrap in debug checks:
```
if (app()->environment('local')) {
    dd($variable);
}
```
Monolog Configuration:
- Issue: Debug logs may clutter production logs if not filtered.
- Fix: Configure handlers in config/packages/monolog.yaml:
```
handlers:
    main:
        level: '%env(APP_LOG_LEVEL)%' # e.g., 'debug' in dev, 'info' in prod
```

Debugging Tips

Toolbar Not Showing:
- Cause: kernel.debug is false or session not started.
- Fix:
  - Set APP_DEBUG=true in .env.
  - Ensure session.start() is called in middleware (Symfony) or StartSession middleware (Laravel).

Data Collectors Not Loading:

Cause: Collectors not registered in the kernel.

Fix: Add to AppKernel (Symfony) or Kernel (Laravel):

protected function registerContainerConfiguration(LoaderInterface $loader) {
    $loader->load(__DIR__.'/config/{packages,parameters}.yaml');
    $loader->load(__DIR__.'/config/{packages}/*_debug.yaml'); // Load debug collectors
}

Custom Dumpers Not Working:

Cause: Dumper not registered with VarDumper.

Fix: Register in a service provider:

use Symfony\Component\VarDumper\Dumper\AbstractDumper;

$this->app->extend('var_dumper', function ($varDumper) {
    $varDumper->addDumper(new class extends AbstractDumper {
        public function dump($var, DumperInterface $dumper) {
            // Custom logic
        }
    });
    return $varDumper;
});

Slow CLI Commands:
- Cause: Debug commands may scan large service containers.
- Fix: Limit output with flags:
```
php artisan debug:container --show-private --limit=10
```

Extension Points

Custom Profiler Panels:

Create a panel for app-specific metrics (e.g., API rate limits):

class RateLimitPanel extends DataCollector {
    public function collect(Request $request, HttpKernelInterface $kernel, Request $masterRequest) {
        $this->data['limits'] = RateLimiter::getStats();
    }
}

Debugging Middleware:

Add middleware to log requests/responses:

class DebugMiddleware implements MiddlewareInterface {
    public function handle(Request $request, Closure $next) {
        if ($request->hasPreviousSession()) {
            dump($request->getSession()->all());
        }
        return $next($request);
    }
}

**Event Listener

Debug Bundle Laravel Package