Debug Laravel Package

Getting Started

1. Install via Composer: composer require spiral/debug --dev
2. Enable in dev environment: Add Spiral\Debug\Bootloader\DebugBootloader::class to app/src/Kernel.php’s bootloaders() method only in dev/staging environments (avoid production).
3. First use: Trigger an exception in a controller; by default, the package replaces Symfony’s default exception handler with enhanced context—including stack traces, request variables, and environment details—rendered in a clean HTML view in the browser.
4. Primary entry point: Start with \Spiral\Debug\Collector\DebugCollector::capture() to manually dump structured data during development.

Implementation Patterns

• Structured Data Collection: Wrap suspected code blocks with DebugCollector::capture($context, 'tag') to log arbitrary data (e.g., variables, DB queries) for inspection via the web UI or CLI dump.
• Middleware Integration: Use DebugMiddleware (from Spiral\Debug\Middleware) to automatically log incoming requests, responses, and timing for specific routes or route groups. Register it in route definitions:

  $router->addRoute('/api/*', [Controller::class, 'handle'], [
      'middleware' => [DebugMiddleware::class],
  ]);
  

• Exception Formatting: Leverage Spiral\Debug\Exception\DebugException or DebugExceptionInterface to tag exceptions with extra context (e.g., user session, DB state) for richer error pages.
• CLI Development: Run php app.php debug:collect (if CLI command exists) or use DebugCollector::flush() in tests/scripts to export captured data to files for later inspection.

Gotchas and Tips

• ⚠️ Environment Lock: Never enable in production—this package does not auto-detect environment; always guard bootloader registration with if ($app->environment() === 'development').
• Output Clashes: If using custom exception handlers (e.g., via Spiral\ExceptionHandler), ensure DebugBootloader loads after your handler or override its configurations to avoid conflicts.
• Silent Failures: capture() calls without output context (e.g., in CLI without -v) may silently store data—always verify output location or set debug.output = 'stream://stdout' in config.
• Config Override: Create app/config/debug.php to tweak:
  • output (e.g., 'file://storage/debug.log' for file logging),
  • max_depth for nested data,
  • collectors to enable/disable DB/Request/Session collectors.
• Modern Alternatives: Since last release was in 2019, prefer Xdebug/Blackfire for production-grade profiling; this package shines for lightweight in-code context logging during Spiral-specific dev workflows, not deep runtime analysis.