Apixception Bundle Laravel Package

Product Decisions This Supports

• Standardizing the public API error contract (primary). The package turns uncaught exceptions into structured JSON with mapped HTTP status codes, instead of framework HTML error pages. That is a contract decision, not just an implementation detail: it determines what every partner, mobile client, and SDK has to parse. Adopting it is a cheap way to make "all errors look the same across services" true by default rather than by convention.
• Client/SDK roadmap sequencing. Typed, predictable error payloads reduce the branching logic in client SDKs and let you ship generated or hand-written clients with a documented error envelope. If an SDK or partner-integration milestone is on the roadmap, this belongs in the sprint immediately before it, not after — retrofitting error shapes later is a breaking change for consumers.
• Build vs. buy for cross-cutting plumbing. Writing exception-to-response mapping is a few days of work and then permanent maintenance across every service that needs it. A small MIT dependency that does it consistently is the classic buy case — with the caveat below about Laravel's own handler.
• Multi-service consistency. If the estate has more than one PHP API, per-team bespoke error handling produces drift: different field names, different status codes for the same condition, different debug leakage. A shared bundle makes the shape a dependency-level default.
• Support and incident-triage economics. Configurable, stable error codes are what make error-rate dashboards, per-error alerting, and support runbooks possible. "Something went wrong" pages generate support tickets; mapped error codes generate self-service answers. This is a measurable reduction in support load, which is a defensible PM metric.
• Security posture in production. Environment-aware debug detail means internal exception messages and stack traces stay out of production responses while remaining visible in development. That's a compliance-adjacent win you can claim without a security project.
• Adoption signal as a decision input. Zero stars and zero dependents means low external validation and a real bus-factor question. That doesn't disqualify it, but it should shape the decision: if we adopt, we should be prepared to vendor or fork it, and that cost belongs in the build-vs-buy math.
• Stack-fit caveat to resolve before committing. This is a Symfony bundle built on kernel events. In a Laravel application, App\Exceptions\Handler and its render() method already own this responsibility, so the honest question is whether the package adds anything beyond what Laravel gives us for free. For Symfony-based PHP services it's a direct fit; for a pure Laravel app, treat it as "probably redundant" until proven otherwise. Frame the decision as which of our PHP services actually need it, not "all of them."

When to Consider This Package

Consider it when:

• You run one or more Symfony-based PHP/API services and want a consistent JSON error envelope without writing and maintaining the listener/handler plumbing in each one.
• You have, or are about to have, external API consumers (partners, mobile apps, published SDKs) and need a stable, documented error contract with mapped HTTP status codes.
• You want environment-aware debug detail — verbose errors in dev, sanitized messages in production — as a configured behavior rather than something each developer remembers to do.
• Your error taxonomy is stable enough that configurable exception-to-status mapping is a maintenance win rather than a config file nobody updates.
• You're comfortable with a low-adoption MIT dependency and have the appetite to vendor or fork it if the maintainer disappears — or you're willing to treat the fork as the real deliverable.
• The alternative is several teams each rolling their own handler, which is the scenario where the consistency win is largest.

Look elsewhere when:

• The application is Laravel-native. Laravel's exception handler already supports custom renders, JSON responses, and debug-mode gating. Adopt this only if a concrete gap is identified (e.g., an existing Symfony-component-based service in the same estate), otherwise you're adding a dependency and a second error path for no gain.
• You need a specific standard error format — e.g., RFC 9457 application/problem+json — and the package's customizable handlers don't cleanly produce it. Check before committing; your consumers may care more about the spec than about internal consistency.
• Procurement or SLO requirements demand a supported dependency with a maintainer SLA, security advisory history, or more than one active contributor. Zero dependents and zero stars is a genuine signal here.
• You need error handling wired into tracing/observability (OpenTelemetry spans, structured log correlation) beyond what the bundle offers — you'd be wrapping it anyway.
• Your team would need heavy customization of handlers and response formats. At that point you're paying the integration cost plus the dependency cost, and an in-house handler of your own design is cheaper to reason about.
• You're on a Symfony version outside the supported constraint range and have no upgrade intent. Verify the minimum supported version before betting on it.

Evidence note: this assessment is derived from the package description and release notes; there is no adoption data, changelog depth, or security history to draw on. Treat the fit assessment as a hypothesis to validate with a short spike in one service before standardizing across the estate.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have an opportunity to make our PHP APIs fail predictably. Today, when something goes wrong, different services return different error shapes — some return HTML error pages, some return inconsistent JSON, some leak internal details in production. That inconsistency costs us in three places: client teams write bespoke error handling, support tickets are harder to resolve because errors aren't self-describing, and any future public API or partner integration inherits the mess. A small open-source component standardizes this: exceptions become structured JSON with correct HTTP status codes, with verbose detail in development and sanitized messages in production. The cost is a dependency and a short integration, not a project. The main caveat is that it's a low-adoption library, so we'd pilot it in one service and be prepared to own a fork if needed — no vendor lock-in, no licensing cost.

For engineering leads: This is a Symfony bundle that hooks kernel events and maps exceptions to JSON responses with configurable status codes. Two things to settle before we commit. First, scope: in pure Laravel services, App\Exceptions\Handler already does most of this — confirm which services actually need it, and don't adopt estate-wide on the assumption that it's free everywhere. Second, ownership: zero stars, zero dependents, single-maintainer signal means we should plan for the possibility of vendoring. The integration itself is small — install, configure the exception-to-status map, confirm the response shape matches what clients expect, and verify production debug output is suppressed. The work is in agreeing the error envelope and documenting it, not in the wiring. If we do this, do it before we publish an API contract to partners, not after.