Trap Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev buggregator/trap -W
   

   Ensure it's added to require-dev in composer.json.

2. Start the Server:

   vendor/bin/trap
   

   The server starts on default ports (9912, 9913, 1025, 8000) and displays dumps in the console by default.

3. First Debug Use Case: Replace dump() with trap() in your Laravel code:

   use Buggregator\Trap\Trap;
   
   // Basic usage
   trap($user); // Sends dump to local server
   
   // With options
   trap($query)->depth(2)->times(5);
   

Key First Steps

• Verify Integration: Run php artisan tinker and test trap() with a complex object (e.g., Eloquent model or request).
• Check Server Output: Ensure dumps appear in the terminal where vendor/bin/trap is running.
• Port Configuration: If using Docker or other services, override ports via CLI:

  vendor/bin/trap -p9912 --ui=8080
  

Implementation Patterns

Core Workflows

1. Debugging in Laravel Controllers

public function show(Request $request, User $user)
{
    // Dump request + user with depth limit
    trap($request->all(), user: $user)->depth(3);

    // Conditional dump (e.g., only for admins)
    if ($request->user()->isAdmin()) {
        trap($user->roles)->once()->if($user->isAdmin());
    }
}

2. Integration with Monolog

Configure Monolog to use Trap as a handler in config/logging.php:

'channels' => [
    'trap' => [
        'driver' => 'monolog',
        'handler' => Buggregator\Trap\Handler\MonologHandler::class,
        'with' => ['port' => env('TRAP_TCP_PORTS', '9912')],
    ],
],

Then log as usual:

Log::channel('trap')->info('User action', ['user_id' => $user->id]);

3. HTTP Dump Middleware

Create middleware to trap incoming requests:

namespace App\Http\Middleware;

use Buggregator\Trap\Trap;
use Closure;

class TrapRequests
{
    public function handle($request, Closure $next)
    {
        trap($request->all(), headers: $request->header())->depth(2);
        return $next($request);
    }
}

Register in app/Http/Kernel.php:

protected $middleware = [
    \App\Http\Middleware\TrapRequests::class,
];

4. Testing SMTP Emails

Use the mail-to-file sender to capture emails:

vendor/bin/trap -smail-to-file

Emails are saved in runtime/mail/{recipient} as JSON files.

5. Performance Profiling

Use tr() (trace + return) for timing critical sections:

$result = $this->processor->process(tr(data: $data));

Laravel-Specific Patterns

• Service Container Binding: Bind Trap to the container for dependency injection:

  $this->app->singleton(Trap::class, function () {
      return new Trap(['sender' => 'server', 'host' => 'localhost']);
  });
  

  Then inject Trap into controllers/services.

• Artisan Commands: Use Trap in custom Artisan commands for debugging:

  use Buggregator\Trap\Trap;
  
  class DebugCommand extends Command
  {
      protected $signature = 'debug:model {model}';
      protected $description = 'Debug a model instance';
  
      public function handle()
      {
          $model = app($this->argument('model'));
          trap($model)->depth(5);
      }
  }
  

• Exception Handling: Override App\Exceptions\Handler to trap exceptions:

  public function report(Throwable $exception)
  {
      trap($exception)->depth(3);
      parent::report($exception);
  }
  

Gotchas and Tips

Common Pitfalls

1. Port Conflicts:

   • Issue: Trap defaults to ports 9912, 9913, 1025, and 8000. If another service (e.g., Laravel Valet, Docker) uses these, dumps may fail silently.
   • Fix: Explicitly set ports via CLI or env vars:

     vendor/bin/trap -p9914 --ui=8081
     

     Or in .env:

     TRAP_TCP_PORTS=9914,9915,1026,8081
     

2. Missing Dumps:

   • Issue: Dumps don’t appear in the server terminal.
   • Debug Steps:
     • Verify the server is running (vendor/bin/trap).
     • Check for errors in the terminal (e.g., port binding failures).
     • Ensure $_SERVER['REMOTE_ADDR'] isn’t overridden (Trap auto-sets it if missing).

3. Protobuf Dump Formatting:

   • Issue: Protobuf messages appear unreadable.
   • Fix: Trap automatically enhances google/protobuf dumps. If not working, ensure the package is loaded before trap() calls.

4. Phar vs. Composer:

   • Issue: Phar version (trap.phar) may not pick up project-specific configs.
   • Fix: Use the Composer-installed version for full integration.

5. Memory Leaks:

   • Issue: Large dumps (e.g., deep arrays) cause high memory usage.
   • Fix: Use depth() and times() limits:

     trap($largeArray)->depth(2)->times(100);
     

Debugging Tips

• CLI Debugging: Use td() (trace + die) to halt execution and inspect state:

  if ($user->isAdmin()) {
      td($user->permissions); // Exit after dump
  }
  

• Remote Server Integration: To send dumps to a remote Buggregator server (e.g., for staging/prod):

  vendor/bin/trap -sserver -hbuggregator.example.com
  

• Conditional Dumps: Use if() to avoid dumping in production:

  trap($sensitiveData)->if(app()->environment('local'));
  

• Custom Senders: Extend Trap’s Sender interface to create a database sender:

  use Buggregator\Trap\Sender;
  
  class DatabaseSender implements Sender
  {
      public function send(array $data): void
      {
          DB::table('debug_dumps')->insert($data);
      }
  }
  

  Register it via:

  vendor/bin/trap -scustom
  

Configuration Quirks

• Environment Variables:

  • TRAP_TCP_HOST: Override the default 127.0.0.1 (e.g., for Docker: host.docker.internal).
  • TRAP_UI_PORT: Change the web UI port (default: 8000).

• Symfony VarDumper: Trap enhances VarDumper globally. To revert to default behavior, exclude Trap’s autoloader or use:

  use Symfony\Component\VarDumper\Cloner\VarCloner;
  $cloner = new VarCloner(); // Bypasses Trap's enhancements
  

• Phar Limitations: The Phar version lacks project-specific configs (e.g., custom senders). Use the Composer version for full features.

Extension Points

1. Custom Handlers: Extend Buggregator\Trap\Handler\HandlerInterface to create a Slack handler:

   class SlackHandler implements HandlerInterface
   {
       public function handle(array $data): void
       {
           $webhook = config('services.slack.webhook');
           Http::post($webhook, ['json' => $data]);
       }
   }
   

   Register via CLI:

   vendor/bin/trap -scustom -hSlackHandler
   

2. Protocol-Specific Traps: Use trap()->protocol('http') to force HTTP dumps (e.g., for API debugging):

   trap($request->json())->protocol('http');
   

3. Asset Uploads: Trap supports uploading files (e.g., images from Storage). Use the asset sender: