Context Exception Laravel Package

Technical Evaluation

Architecture fit. fab2s/context-exception is an interface-first micro-package: it defines a contract for "an exception that carries structured context" plus a ready-made implementation/trait. That shape fits well. It is framework-agnostic and composes with Laravel's exception pipeline rather than replacing it, and the interface inversion means our domain layer can type-hint a contract while the vendor code stays at the edges. This is the correct dependency direction for a typed exception taxonomy (payments, auth, upstream HTTP failures) in a modular monolith or a service that shares code with CLI/queue workers.

The important caveat: Laravel 11+ already ships Illuminate\Support\Context, Exception::context(), and default handler behavior that includes context in logs. The genuine delta here is (a) an explicit typed interface you can match on in report(), (b) context composition across getPrevious() chains, and (c) reuse outside Laravel. If the only requirement is "log structured data with exceptions," the framework already covers it and this package is redundant.

Integration feasibility. High and cheap. A Composer require, implementing the contract on a handful of domain exceptions, and a decorator in the handler. Expect days, not sprints: no migrations, no published config, no service provider of note. No schema or API surface changes for consumers.

Technical risk. The dominant risk is adoption, not engineering. Three stars, zero dependents, and a single maintainer means no third-party code review and a bus factor of one. The package is small enough that a security or quality defect is unlikely to hide for long, but also small enough that a composer audit finding or a PHP version bump could go unaddressed for a release cycle. Secondary risks are overlap and payload discipline: two competing context mechanisms (this package and Laravel's facade) produce half-populated, inconsistent debugging data; and unbounded context arrays (full request, full query result) inflate logs, raise ingestion cost, and leak PII or tokens into log storage and API error responses.

Key questions.

• What PHP and framework versions are constrained, and is there CI with a coverage signal?
• Is context immutable after construction, and does it merge context from previous exceptions?
• Are there depth or size limits and any redaction hooks, or does the package serialize anything it is given?
• Do trait method names (getContext, setContext, withContext) collide with Laravel's existing exception methods?
• What does the maintainer's release and response cadence look like over the last 12 months?
• What is the exit cost? (If it is one or two methods, this is near zero and the risk is mostly cosmetic.)

Integration Approach

Stack fit. Laravel 10–12 fits cleanly; the package is equally usable from queue workers, Artisan commands, and any non-Laravel PHP services in the same repository. It pairs naturally with a consistent JSON error envelope, since context can be promoted to a meta or debug block behind an environment gate.

Migration path. Do not let the vendor interface spread. Introduce a thin internal adapter — either our own HasContext contract that the vendor interface satisfies, or a single ContextExtractor used by the handler — so the vendor symbol appears in one or two files. Start with new code paths only; retrofitting existing exceptions is optional and low value. Where the framework's native context already covers a case, prefer it and use this package only for the contract and previous-exception composition.

Compatibility. Verify the PHP constraint against runtime before committing, and confirm no method-name collisions with Laravel's context()/withContext(). Test error rendering in both local and production so context does not silently reach API consumers. Confirm the package does not assume a specific PSR-3 logger.

Sequencing.

1. Branch spike: wire the handler, confirm log output and JSON rendering end to end.
2. Add the internal contract plus adapter at the application boundary.
3. Apply to the three highest-value exception families (payment, auth, upstream integration).
4. Add a redaction policy and a hard size cap in the handler before any broader rollout.
5. Codify "what belongs in context" in the PR checklist and the exception base class.
6. Re-evaluate after one quarter against native Laravel; drop the dependency if the delta is not real.

Operational Impact

Maintenance. MIT, tiny surface, stable by construction — but a single-maintainer package with no external dependents gets no implicit regression testing from the ecosystem. Pin the version, review changelogs on upgrade, and treat a stalled release as expected rather than exceptional.

Support. No commercial support and no community to lean on. Internal ownership is mandatory: name a platform-team owner and document the adapter as the supported entry point.

Scaling. Runtime cost is negligible. The real scaling cost is log volume: exception payloads can grow 2–5x once context carries request metadata or query fragments. Budget for log ingestion before enabling it broadly, and cap context size in code rather than in policy.

Failure modes.

• Handler throws while serializing non-scalar context (closures, resources, large object graphs), masking the original exception — the most serious failure and the one to guard first.
• Unbounded context saturates the log pipeline or exposes secrets/PII in logs and error responses.
• Two context systems coexist, producing partially populated debugging data and eroding trust in the signal.
• Abandonment leaves a pinned, unpatched dependency — low impact given the exit cost, but it needs the internal adapter to stay cheap.

Ramp-up. Effectively zero for a mid-level engineer: one interface, one trait, one handler hook. The actual ramp-up is team discipline — agreeing what belongs in context, what must be redacted, and when to use this versus Laravel's native context. That convention work is the real deliverable; the package is a 15-minute install wrapped around it.