CLI tool
nunomaduro/collision avatar
nunomaduro/collision

nunomaduro/collision: readable PHP CLI error reporting

💥 Collision is a beautiful error reporting tool for command-line applications

4,664 stars187 forksPHPMIT

At a glance

What is it?
Collision is a PHP package that replaces raw stack traces with formatted error output for command-line applications. It ships inside Laravel and can be registered manually in any PHP project, but it does not fix errors, only present them.
Who is it for?
Adopt Collision if you run PHP from the terminal and want exception output that a human can read: Laravel projects already have it, and other projects can register the provider in one line. Do not adopt it as a production error tracker, since it is a dev dependency that formats exceptions rather than recording them.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • nunomaduro/collision4,664 ★ · +6
Star history
Repository2026-09-232026-11-15
nunomaduro/collision4.7k4.7k

6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Collision changes about a PHP stack trace

A PHP exception printed to a terminal is a wall of frames: file paths, function signatures, argument values, and vendor internals, all in the same weight. Collision is a package that intercepts that output and renders it differently, with the failing frame separated from the surrounding call chain and the message given room to breathe. The README describes it as "a package designed to give you beautiful error reporting when interacting with your app through the command line".

The audience is narrow and specific. This is for PHP developers who spend their day in a terminal: running a console command, a test suite, or a framework task, and reading the failure in the same window. It is not a browser error page, and it is not a log aggregator. If your PHP only ever runs behind a web server and your errors arrive in Sentry or a log file, Collision has little to offer you.

The package is built on top of Whoops, the long-standing PHP error handler, so the rendering pipeline is not written from scratch. Collision's contribution is the CLI presentation layer and the framework integrations.

How the handler is registered and where output comes from

Collision works by registering an error handler that takes over exception rendering for the process. The README states that it is built on top of Whoops and that it supports Laravel, Symfony, PHPUnit, and other frameworks. In a framework with an adapter, that registration happens for you as part of the framework's console bootstrap. Without an adapter, the README gives exactly one line of setup: you instantiate the provider and call register on it. From that point, exceptions thrown in the process are routed through Collision's renderer instead of PHP's default handler.

The consequence of this design is that Collision is a presentation layer and nothing more. It does not catch exceptions you have already caught yourself, and it does not change control flow. If your code wraps a failure in a try/catch and prints its own message, Collision never sees it. The same applies to errors written to a logger before they propagate. The handler only gets what actually reaches the top of the process.

There is also a version dimension to this. The README's compatibility table maps Laravel 6.x through 12.x onto Collision 3.x through 8.x, and pairs recent Collision releases with specific PHPUnit and Pest versions. Laravel 11.x and 12.x sit on Collision 8.x, alongside PHPUnit 10.x through 13.x and Pest 2.x through 5.x. That table is the practical contract: the package tracks framework and test runner releases rather than promising independence from them.

Installing Collision with Composer and registering it without a framework

Collision requires PHP 8.2 or newer, per the README. Install it with Composer as a dev dependency, which is the form the README shows:

bash
composer require nunomaduro/collision --dev

If you are on an older framework, the README shows pinning a major version instead. For Laravel 8.x, the documented command is:

bash
composer require nunomaduro/collision:^5.0 --dev

On Laravel itself you can stop here. The README says Collision is included on Laravel, so the handler is already wired up and console errors are formatted without further work. For any other PHP project, there is no adapter, and the README gives the registration snippet directly:

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

Put that line early in your entry point, before the code that might throw. The next uncaught exception in that process should render through Collision rather than as a plain PHP trace. If your project has its own console bootstrap or a front controller, that is the place for it; registering it inside a class that is only loaded on demand will not help, because the handler has to be active before the failure happens.

Where Collision stops being the right tool

The first limitation is in the installation command itself: --dev. Collision belongs to the development dependency set. It is there to make failures legible while you work, not to be the error path in production. A production PHP process that relies on Collision for error handling has no durable record of what went wrong, because the output goes to a terminal that, in production, may not exist.

The second limitation follows from the handler model. Because Collision only renders exceptions that reach the top of the process, it cannot help with failures that are swallowed, converted, or logged earlier. In a large application with layered exception handling, the interesting context may already be gone by the time the renderer runs.

Third, the compatibility table is a maintenance obligation, not a convenience. The mapping from Laravel versions to Collision majors means that upgrading the framework can require a matching Collision upgrade, and the README pairs each recent Collision line with a specific PHPUnit and Pest range. A project that pins PHPUnit tightly and also wants the newest Collision may find those two constraints in conflict. The README does not document a rollback path or a migration guide between majors; the table is the only guidance it offers.

Finally, the repository's docs directory exists but the README itself is thin. Installation, the compatibility table, the no-adapter snippet, and contribution pointers are essentially the whole document. Anyone expecting configuration options for themes, output width, or verbosity will not find them described there.

Collision against plain Whoops and framework error pages

The obvious alternative is Whoops on its own, which Collision is built on top of. The difference in approach is that Whoops is a general error handler with a browser-oriented presentation and a stack of handlers you configure yourself, while Collision is the CLI-shaped layer over it, with the framework and test-runner integrations already written. If you want to control handler ordering, custom inspectors, or the HTML page, going to Whoops directly gives you that surface. If you only want terminal output that reads well and you are on Laravel, Symfony, or PHPUnit, Collision is the shorter path.

The other comparison worth making is against the framework's own console error output. Laravel, Symfony, and PHPUnit each render exceptions in their own way, and Collision's value is precisely that it replaces those renderings with a consistent one. That is also its cost: you are opting out of whatever the framework's default renderer did, including any custom formatting your team added there. In a project that has already tailored its exception rendering, Collision is a replacement, not an addition.

Maintenance status, licence, and the cost of keeping up

Collision is not archived, and the last push to the default branch v8.x was on 2026-10-14. The README lists Nuno Maduro as creator and maintainer, and the repository carries a CONTRIBUTING.md and a SECURITY.md alongside the source, tests, scripts, and a phpstan configuration. The docs directory is present at the top level. The repository has no published GitHub releases.

The licence is MIT, stated in the README and in the LICENSE.md file at the repository root. In practical terms that is a permissive licence. This is not legal advice; read LICENSE.md if your organisation has specific requirements.

The upgrade cost is the compatibility table. Because Collision majors are tied to Laravel majors and to PHPUnit and Pest ranges, the package tends to move when your framework moves. Treat the --dev placement as a signal about scope: it is a development-time rendering tool, and the maintenance you are signing up for is keeping its major version aligned with the framework and test runner you already run.

Editorial conclusion

Adopt Collision if you run PHP from the terminal and want exception output that a human can read: Laravel projects already have it, and other projects can register the provider in one line. Do not adopt it as a production error tracker, since it is a dev dependency that formats exceptions rather than recording them. Before upgrading, check the version compatibility table, because a Laravel or PHPUnit bump can force a Collision major version with it.

Frequently asked questions

What PHP version does nunomaduro/collision require?

The README states that Collision requires PHP 8.2 or newer.

How do I install nunomaduro/collision in a project that is not Laravel?

Require it with Composer as a dev dependency, then register the handler in your code with (new \NunoMaduro\Collision\Provider)->register(). The README labels this the no-adapter case.

Which Collision version goes with which Laravel version?

The README's compatibility table maps Laravel 6.x to Collision 3.x, 7.x to 4.x, 8.x to 5.x, 9.x and 10.x to 6.x, 10.x to 7.x, and 11.x and 12.x to 8.x. It also pairs recent Collision lines with PHPUnit and Pest ranges.

What is Collision built on top of?

The README states that Collision is built on top of the Whoops error handler, and that it supports Laravel, Symfony, PHPUnit, and many other frameworks.

Official sources

  1. Issues
  2. License: MIT
  3. nunomaduro/collision on GitHub
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/nunomaduro-collision.svg)](https://hysenlabs.com/projects/nunomaduro-collision)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/nunomaduro-collision.svg)](https://hysenlabs.com/projects/nunomaduro-collision)

Was this useful?