Collision: Formatted Error Reporting for PHP Command-Line Applications

What Collision Solves and Who Uses It

When a PHP application running in a terminal throws an exception, the default output is a wall of text: the exception class, a message, a file path, a line number, and a raw stack trace. Collision reformats that output into something a developer can read and act on quickly, with syntax highlighting, a code frame showing the relevant lines around the error, and clearly structured context.

The primary users are PHP developers who build and test applications through the command line: developers running artisan commands in Laravel, writing test suites with PHPUnit or Pest, or working with Symfony's console component. Collision is described as "a package designed to give you beautiful error reporting when interacting with your app through the command line."

It is built on top of Whoops, a widely used PHP error handler that handles both CLI and web contexts. Collision is the CLI-specific layer that reformats Whoops output for terminal display. Whoops handles web error pages; Collision handles the terminal.

Laravel Inclusion and Framework Compatibility

Collision ships bundled with Laravel. The README states it is "included on Laravel, the most popular free, open-source PHP framework in the world." This means any new Laravel project already has Collision without a separate install step.

Beyond Laravel, Collision supports Symfony, PHPUnit, and "many other frameworks." The README does not enumerate every supported framework in detail, but the Whoops foundation provides broad compatibility.

Collision is maintained by Nuno Maduro, who is also the author of Pest. The tight version coupling between Collision, Laravel, PHPUnit, and Pest creates a stable compatibility matrix, but it also means using an unsupported combination can cause unexpected behavior.

Installation and Version Pinning

Collision requires PHP 8.2 or higher. Install it via Composer as a development dependency:

composer require nunomaduro/collision --dev

For projects on older versions of Laravel, pin to the matching Collision version. The README provides the full table:

- Laravel 11.x, 12.x: use Collision 8.x, which supports PHPUnit 10.x through 13.x and Pest 2.x through 5.x - Laravel 10.x with Pest 2.x: use Collision 7.x with PHPUnit 10.x - Laravel 9.x, 10.x without Pest: use Collision 6.x - Laravel 8.x: use Collision 5.x

For an explicit pin to a major version, pass the version constraint:

composer require nunomaduro/collision:^5.0 --dev

The --dev flag installs Collision only in the development and testing environments. It is not required in the production container where no developer is watching terminal output.

Registering Collision Without a Framework

When using Collision without Laravel or another framework that registers it automatically, you must register the error handler in your application bootstrap:

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

This call hooks into PHP's error handling and exception handling mechanisms. Once registered, any uncaught exception or error will route through Collision's formatter instead of PHP's default output. The README shows this as the minimal integration path for framework-agnostic or custom console applications.

Framework adapters for Laravel and Symfony handle this registration step automatically during the framework's bootstrap sequence. PHPUnit and Pest projects also register it automatically when Collision is present, formatting test failure output through the same formatter.

Collision 8.x and the PHPUnit/Pest Version Matrix

Collision 8.x is the current major version for Laravel 11 and 12. It supports a wide range of PHPUnit versions: 10.x, 11.x, 12.x, and 13.x. For Pest it supports versions 2.x, 3.x, 4.x, and 5.x. This broad PHPUnit compatibility reflects the ecosystem's transition from PHPUnit 10 through the newer major versions during the Laravel 11 and 12 lifecycle.

For projects upgrading from Laravel 10 to Laravel 11, the Collision version must also be updated from 7.x to 8.x. Running Collision 7.x with Laravel 11 is not a supported combination in the README's compatibility table.

The repository is on the v8.x default branch, which means cloning the repository without specifying a branch gives you the current major version's code. Older version branches exist but are not the default.

Whoops as the Foundation and What Collision Does Not Do

Collision wraps Whoops, which means Collision inherits Whoops' core error capture mechanism. Whoops has separate formatters for HTML (browser error pages), JSON, and CLI output. Collision is specifically the CLI formatter layer on top of Whoops, designed for terminal rendering with color and framing.

This boundary matters for teams that use both web and CLI contexts. Collision improves the terminal experience. It does not change what happens when a Laravel application throws an exception during an HTTP request and renders an error page in the browser. For that, Whoops or Laravel's own exception handler is responsible.

Collision does not add error aggregation, alerting, or remote logging. It is a formatting layer, not a monitoring system. Teams that need exception monitoring in production (capturing errors from deployed applications and routing them to dashboards) use separate tools like Flare, Sentry, or Bugsnag alongside Collision.

The MIT license applies. The last push to the repository was on 2026-08-04. The repository structure includes a src/ directory for the formatter code, a tests/ directory, and a docs/ folder alongside standard Composer configuration files. The SECURITY.md and CONTRIBUTING.md files document the project's security policy and contribution guidelines for community contributors.

Editorial conclusion

Collision is the right package for any PHP project where developers interact with the application through a terminal and need readable exception output instead of raw stack traces. It is included in Laravel automatically, so most Laravel 11 and 12 projects already have it without an explicit install step. For non-Laravel projects, the version compatibility table in the README is the correct reference for choosing the right Collision version against your PHP version, PHPUnit version, or Pest version. The package does not improve web-based error pages; for that purpose, the underlying Whoops library is the appropriate tool.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nunomaduro/collision on GitHub
4. Project website
5. README