Collision Adapter Symfony Laravel Package

Product Decisions This Supports

• Whether to invest in developer-experience (DX) for internal CLI tooling. Standardizing error output across Symfony Console utilities (deploy scripts, data pipelines, codegen, admin tools) is a few engineering hours versus living with terse default renderers. Frame it as a small DX bet, not a platform initiative.
• Build vs. buy on console error formatting. Rather than hand-rolling exception renderers per tool, this thin MIT adapter buys into the proven Collision renderer with a near-zero configuration surface. The honest comparison is adapter + Collision versus pulling nunomaduro/collision in directly — the adapter's incremental contribution is the framework metadata line plus consistent wiring.
• Standardizing debugging UX across a mixed PHP estate. If the org runs both Laravel and Symfony Console apps, this aligns error presentation and debugging workflows under one mental model, reducing context-switching and onboarding time.
• Separating "pretty errors" from production observability. Collision improves human-readable local error output; it is explicitly not production error tracking. Adopting it forces an explicit pairing decision with Sentry, Bugsnag, or OpenTelemetry so nobody mistakes readable local traces for a production safety net.
• Framing scope correctly — this is glue, not a renderer. The package only tells Collision the Symfony framework name and version. If the value story is miscommunicated as "Collision for Symfony," teams will adopt it expecting dramatically better errors, see little change, and conclude it is broken. Get the framing right before it reaches a roadmap conversation.
• Dependency governance calibration. With ~44 stars, 0 listed dependents, and a single maintainer, this is a live test case for dependency policy: adopt-and-pin, vendor, or inline the small adapter rather than treating it as a strategic dependency.

When to Consider This Package

Adopt it when:

• You maintain Symfony Console applications or standalone CLI tools outside Laravel and want Collision-style error rendering without reimplementing it.
• Your team already knows Collision from Laravel and wants consistent debugging ergonomics in non-Laravel PHP CLIs.
• The integration point is development/test contexts or internal CLIs, not critical production error-handling paths.
• You are comfortable with a low-adoption, small-footprint adapter and can pin a version, vendor it, or fork the thin listener if upstream stalls.
• You want a low-blast-radius POC — a dev-dependency install plus two registration lines behind an APP_DEBUG guard, with rollback being a Composer remove plus one deleted line.

Look elsewhere when:

• You are on Laravel — Collision already ships through laravel/framework and the adapter is redundant. Stop here; this is the most common false positive.
• You need production-grade error monitoring or alerting — use Sentry, Bugsnag, or OpenTelemetry; Collision is not that.
• You are not on Symfony Console, or the error surface is HTTP — that path must keep symfony/error-handler; mixing the two handlers causes double-rendering.
• Governance requires actively maintained dependencies with meaningful adoption. Treat this as "a small utility we may need to own," not a strategic commitment — check commit recency and plan to vendor or fork.
• You expect a visibly different error experience. If stock Collision output already satisfies you, the adapter's contribution may not clear the bar for adding a dependency.

Sequencing: POC on one low-blast-radius internal CLI with APP_DEBUG gating and confirm the framework metadata line actually appears — stock-looking Collision with no framework line means it is not wired in. Then test the awkward paths (-vvv, malformed exceptions, non-TTY/CI capture for ANSI garbage). Roll to remaining internal CLIs. Defer customer- or partner-facing CLI tooling until the adapter has survived at least one Symfony Console or Collision major-release cycle.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, MIT-licensed developer-experience improvement that makes errors in our command-line tools easier to read and debug, shortening onboarding and troubleshooting time for engineers. Risk is contained: it is a thin adapter, not a platform commitment, and can be removed, vendored, or inlined at minimal cost. It supports internal-tooling and developer-productivity goals rather than customer-facing roadmap items. Be candid about the size of the win — it is an incremental ergonomics improvement for internal CLIs — and make explicit that a separate decision is still needed on production error tracking.

For engineering: Collision is the de facto pretty error handler for PHP consoles; this adapter wires it into Symfony Console so our CLIs get readable traces and the correct framework metadata line instead of the stock Symfony renderer. It is deliberately thin — Collision does the rendering, this package only makes Collision aware of Symfony — so frame the value accurately, or you will get a false negative. Integration is small and isolated: register Collision with the adapter at the console entrypoint before the kernel boots, keep it out of production error-handling paths, and pin both packages in composer.lock. Three runbook caveats: register Collision last so it overrides any earlier PHP exception handler (otherwise it can mask the original exception at the exact moment clear output matters most); gate it behind APP_DEBUG (or --no-ansi in CI) to avoid ANSI noise in logs; and verify three version axes — PHP minimum, Symfony Console major, and the transitive Collision major — against what CI actually resolves. Because adoption is low, plan to vendor or fork if upstream stalls; the adapter surface is small enough that a mid-level engineer can read and own it in a sitting. Pair it with a real error-tracking tool for production.