Collision Adapter Symfony Laravel Package

Technical Evaluation

Architecture fit. This is deliberately thin glue, not a framework feature. The adapter's entire job is to tell Collision the Symfony framework name and version so Collision can print a correct framework metadata line next to its exception rendering. Collision does the rendering; Symfony Console still dispatches the error; nothing touches the DI container, HTTP kernel, data layer, or business logic. For a TPM that maps to a near-minimal dependency shape: one file at the presentation edge of the console path, trivially removable, with no production runtime footprint.

Laravel-specific verdict — read this first. If the target application is Laravel, stop. Collision already ships transitively through laravel/framework; adopting this adapter adds a dependency to deliver a framework metadata line Laravel already provides. The only defensible use is a mixed PHP estate where the org also maintains standalone Symfony Console CLIs (deploy scripts, data pipelines, codegen, admin utilities) and wants the same debugging mental model the Laravel teams already have. Frame the decision as "standardize console error ergonomics across non-Laravel CLIs using the renderer our Laravel engineers already know" — not as "Laravel tooling."

Integration feasibility. High, and cheap to falsify. Composer-installable, MIT, no native extensions, no daemon, no configuration schema. A POC is a --dev install plus two registration lines in bin/console behind an APP_DEBUG guard — hours, not days. The absence of a config surface is a feature; if the team starts asking to configure it, that's a signal we're using the wrong tool.

Technical risk. The risk is ownership and framing, not code quality. Four exposures:

1. Weak adoption signal. 44 stars, 0 listed dependents, single maintainer. First-party to the Collision author, which supports provenance but not bus factor — no SLA, no documented security disclosure process.
2. Narrow version coupling. The adapter contract has churned across Collision majors (v6 → v7 → v8) and is sensitive to Symfony Console majors. A bump on either side can break it before a patch ships, and with no downstream crowd we are the discoverer.
3. Scope misunderstanding is the real trap. Stakeholders may hear "Collision for Symfony" and expect visibly better errors. They will get the same Collision rendering plus a framework line. If the value story is oversold, teams adopt it, observe little change, and conclude it's broken.
4. Error-path amplification. Collision installs a PHP exception handler and runs only on the failure path. Registering it before Symfony's ErrorHandler — or failing to ensure it runs last — can mean the handler never fires, or that the adapter masks the original exception at the exact moment clear output matters most.

Key questions. Is the target genuinely a Symfony Console app outside Laravel? (If not, close the ticket.) Do we already pull Collision for another reason, making the marginal cost one line? What is our acceptable lag behind Symfony Console majors, and who owns verification when one lands? Is the adapter small enough to vendor in-house, and has anyone actually confirmed that? Does dependency governance accept single-maintainer, low-adoption packages on CLI entrypoints? And has engineering confirmed precisely what this package contributes versus Collision, so the pitch is accurate?

Integration Approach

Stack fit. PHP 8.x, Symfony Console 6/7, Collision 7/8, installed as a --dev dependency. A no-op for Laravel and irrelevant to HTTP. Scope explicitly to non-Laravel console entrypoints — bin/console and long-running worker boot scripts — and keep it out of public/index.php, which must retain symfony/error-handler. Mixing the two handlers produces double-rendering.

Migration path. Add the dev dependency pair (Collision plus the adapter), then register Collision with the Symfony adapter in the CLI bootstrap before the kernel boots and before Application::run(). No schema change, no data migration, no API change — output formatting only. Rollback is a Composer remove plus deleting the registration lines; blast radius is one file per entrypoint.

Compatibility. Verify three axes before merging: PHP minimum, Symfony Console major, and the transitive Collision major. Pin both packages in composer.lock and confirm the pins match what CI actually resolves — low adoption means constraint drift will not be caught upstream. Check the adapter contract for the target Collision major, since the interface changed between v6, v7, and v8. Confirm symfony/var-dumper sits in the same dev block so dump()/dd() render consistently inside Collision output.

Sequencing. (1) POC on one low-blast-radius internal CLI with APP_DEBUG gating; confirm the framework metadata line actually appears — stock-looking Collision with no framework line means the adapter isn't wired in. (2) Exercise the awkward paths: -vvv verbosity, deliberately malformed exceptions, and non-TTY/CI capture for ANSI garbage or truncation. (3) Batch-roll remaining internal CLIs. (4) Hold customer- or partner-facing CLI tooling until the adapter has survived at least one Symfony Console or Collision major cycle. Write the registration-ordering rule (Collision last) into the runbook during step 2, not after an incident.

Operational Impact

Maintenance. Near-zero routine cost — no runtime services, minimal code, no configuration to drift. The genuine burden is upgrade choreography: every Symfony Console or Collision major requires someone to verify resolution and rendering. Budget a small recurring review item rather than treating this as inert; the failure mode of "nobody checked" is a broken CLI the morning of a framework bump.

Support. Community-only. No vendor, no paid tier, no security response process. Acceptable for internal developer tooling; a governance flag for anything revenue-facing or externally shipped. Lock-in is negligible because the fallback is cheap: vendor the adapter into our repo, or drop it and accept Symfony's stock console rendering. State the position as "we own this if upstream stops," not "we depend on upstream."

Scaling. Effectively free. Collision and the adapter activate only on the error path, so there is no throughput, latency, or memory implication for successful command execution. Scaling concerns here are organizational: how many CLIs depend on it, and how many engineers need to know the registration-ordering rule.

Failure modes. Three to instrument and mitigate. (a) Boot-time fatal from a version mismatch — surfaces immediately in CI, which is the good case; the pin plus a smoke test covers it. (b) Exception masking — Collision or bad adapter metadata throws while rendering and obscures the original fault; mitigate with a test that throws a deliberately malformed exception and by registering Collision last so Symfony's handler remains the fallback. (c) ANSI garbage or truncated output in non-TTY contexts such as CI runners and log aggregators; mitigate by capturing and diffing console output in a pipeline test and documenting --no-ansi gating. None of these risk silent data loss or customer impact provided the package stays in dev/CLI scope.

Ramp-up. Under an hour for any engineer who has worked with Symfony Console or Laravel. The whole adapter can be read in a sitting, which is what makes the bus-factor risk tolerable — a mid-level engineer can own, vendor, or replace it. Pair it with a real error-tracking tool (Sentry, Bugsnag, OpenTelemetry) for production; Collision improves human-readable local output, and nothing about this adoption should let the organization mistake pretty traces for a production safety net.