Collision Laravel Package

Getting Started

Collision is a drop-in error handler for CLI PHP applications, especially prominent in Laravel (via php artisan). Its primary value is transforming cryptic PHP errors into beautifully rendered, context-rich stack traces—complete with code snippets, syntax highlighting, and helpful suggestions.

First steps:

1. Require the package for development: composer require nunomaduro/collision --dev
2. In Laravel (Laravel 10+ uses Collision by default), no manual registration is needed—php artisan commands will automatically use it.
3. In non-Laravel CLI apps (e.g., custom Symfony commands or plain PHP scripts), register it once at bootstrap:

   (new \NunoMaduro\Collision\Provider)->register();
   

First use case: Run a broken Artisan command like php artisan make:controller with an invalid namespace—watch Collision turn a messy FatalError into a clean, colorized output with line highlights and actionable hints.

Implementation Patterns

Collision integrates natively with Laravel’s console kernel and command resolution. Beyond that, it shines in testing, custom CLI tools, and Laravel Zero apps.

Common workflows:

• Laravel development: No configuration needed. Collision activates automatically when running php artisan. Its error screen appears even for uncaught exceptions, handler exceptions, or validation errors.
• Testing: Works seamlessly with Pest and PHPUnit. Add a register call in phpunit.xml bootstrap or Pest.php / bootstrap/app.php to enhance test output. Example in a test bootstrap:

  if (class_exists(\NunoMaduro\Collision\Provider::class)) {
      (new \NunoMaduro\Collision\Provider)->register();
  }
  

• Laravel Zero / custom CLI tools: Register the provider in bootstrap/app.php, just before $app->run(). This ensures all command errors are rendered consistently.
• Symfonian apps (e.g., Symfony Console standalone):

  $application = new Application();
  (new \NunoMaduro\Collision\Provider)->register();
  $application->run();
  

Pro tip: Use --no-ansi or TERM=dumb to disable Colorful output for CI logs or tools like Laravel Horizon that may misrender ANSI sequences.

Gotchas and Tips

• Version mismatch: Collision is versioned tightly to Laravel and PHPUnit. Always check the version compatibility table before upgrading. Using Collision 8.x with Laravel 9.x leads to silent failures or missing features.
• No handler registration in Laravel: While Laravel registers it automatically, make sure your app/Exceptions/Handler.php hasn’t overridden the console exception rendering in a way that bypasses Collision (e.g., renderForConsole() returning early).
• Termwind dependency: Collision depends on nunomaduro/termwind for rendering. If your project limits dependencies, be aware of this transitive requirement—especially in containerized or minimal environments.
• Customizing output: Collision supports customization via config. Publish its config (php artisan vendor:publish --provider="NunoMaduro\Collision\CollisionServiceProvider") to tweak themes (e.g., dark, light, catppuccin), max frames, or disable hints.
• Debugging silent failures: If errors aren’t colored, first check:
  • php artisan --version → confirms Collision is active
  • PHP version ≥ 8.2 (required in v8+)
  • Whether WHOOPS_ENABLE or SHELL_VERBOSITY settings interfere
• Extensibility: Collision uses adapters for framework-specific insights (e.g., Laravel’s route suggestions for 404s in console). You can implement your own Adapter to inject domain-specific context into error hints. See src/Adapters/Laravel/ for examples.