Debug Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation:

   composer require symfony/debug
   

   Laravel already includes this package via Symfony's components, so no additional config is needed.

2. First Use Case:

   • Debugging Variables: Use dump() or dd() in Tinker or controllers:

     use Symfony\Component\VarDumper\VarDumper;
     
     $user = User::find(1);
     VarDumper::dump($user); // Dump without halting execution
     VarDumper::dump($user, true); // Halt execution (like dd())
     

   • Enable Debug Mode: Ensure APP_DEBUG=true in .env for full stack traces and error details.

3. Where to Look First:

   • Symfony VarDumper Docs for advanced usage.
   • Laravel’s built-in dump()/dd() helpers (aliases for VarDumper).

Implementation Patterns

Core Workflows

1. Debugging Requests/Responses:

   // Log HTTP request data
   dd(request()->all(), response()->headers->all());
   

   • Useful for API debugging or middleware inspection.

2. Database Queries:

   $query = User::where('active', true)->toSql();
   dd($query, [$user->id]); // Show raw SQL + bindings
   

   • Combine with Laravel’s DB::enableQueryLog() for deeper SQL analysis.

3. Tinker Integration:

   php artisan tinker
   

   • Use dump()/dd() interactively to explore Eloquent models or service containers.

4. Custom Dumpers:

   • Extend Symfony\Component\VarDumper\Cloner\Data to handle custom objects:

     class MyCloner extends \Symfony\Component\VarDumper\Cloner\Data
     {
         public function __clone()
         {
             // Custom logic for your class
         }
     }
     

   • Register via service provider:

     VarDumper::setHandler(function ($var) {
         return new \Symfony\Component\VarDumper\Dumper\HtmlDumper(new MyCloner());
     });
     

5. Error Handling:

   • Replace try-catch blocks with dd() for quick error inspection:

     try {
         $result = riskyOperation();
     } catch (\Exception $e) {
         dd($e, ['context' => 'operation']); // Inspect exception + metadata
     }
     

Integration Tips

• Laravel Debugbar: Pair with barryvdh/laravel-debugbar for a UI-based debugger.
• Logging: Use dump() in logs via Log::debug(dump($var)) for structured debugging.
• Testing: Replace assertEquals() with dd() in PHPUnit tests for ad-hoc debugging.

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • dd() halts execution; avoid in production or high-traffic routes.
   • Use dump() for non-blocking debugging in live environments (if APP_DEBUG=true).

2. Circular References:

   • Deeply nested objects may cause infinite loops. Use VarDumper::setMaxItems() to limit depth:

     VarDumper::setMaxItems(50); // Default is 100
     

3. Output Buffering:

   • Headless environments (CLI, queues) may not display output. Redirect to a file:

     file_put_contents('debug.log', dump($var));
     

4. Custom Objects:

   • Without a custom cloner, complex objects (e.g., closures, resources) may dump poorly. Implement __debugInfo():

     class MyModel {
         public function __debugInfo() {
             return ['id' => $this->id, 'name' => $this->name];
         }
     }
     

5. Environment-Specific Debugging:

   • Disable dd() in production via middleware:

     if (!app()->environment('local')) {
         abort_if(true, 403); // Bypass dd() in non-local envs
     }
     

Tips

1. Color Output:

   • Enable ANSI colors for better readability (default in Laravel Tinker):

     VarDumper::setHandler(new \Symfony\Component\VarDumper\Dumper\CliDumper());
     

2. HTML Dumping:

   • Useful for Blade debugging:

     dd(view('emails.welcome')->render());
     

3. Debugging Exceptions:

   • Combine with Laravel’s exception handler to log full traces:

     App\Exceptions\Handler::render($request, $e) {
         if ($request->wantsJson()) {
             return response()->json(['error' => $e->getMessage(), 'trace' => $e->getTrace()]);
         }
         return parent::render($request, $e);
     }
     

4. Debugging Queues:

   • Use dd() in handle() methods or inspect jobs via queue:work --once --verbose.

5. Profiling:

   • Time-critical sections:

     $start = microtime(true);
     // ... code ...
     $duration = microtime(true) - $start;
     dump("Duration: {$duration}s");
     

6. Configuration:

   • Override defaults in config/var_dumper.php (if manually configured):

     'max_items' => 1000,
     'max_depth' => 10,