Exceptional Validation Laravel Package

Product Decisions This Supports

• API error-contract standardization. The package is about mapping exceptions to structured responses (validation failures, embedded violation lists, UID-based conditions). This directly supports the decision to publish a single, documented error envelope for all JSON consumers instead of accumulating ad-hoc render() overrides per controller.
• Build vs. buy on the exception layer. Every Laravel API eventually grows a bespoke Handler/Exceptions folder. This package lets you adopt a small, declarative mapping layer rather than funding an internal framework. The right comparison is "one sprint of internal plumbing + permanent maintenance" vs. "one small Composer dependency."
• Roadmap input for API hardening / public API work. If the roadmap includes partner integrations, a public API, mobile clients, or versioned endpoints, consistent machine-readable errors are a prerequisite. Adopting this is a cheap enabler for that workstream; deferring it is a deliberate choice to keep error semantics tribal knowledge.
• Module ownership decisions. Declarative exception→response mapping lets domain modules declare their own failure semantics without editing a central handler — relevant if you're splitting a monolith or planning team-scaling refactors.
• Use cases that fit well: REST/JSON backends with domain-specific exceptions (payment declined, quota exceeded, resource locked), apps where Laravel's ValidationException shape needs to be normalized alongside non-validation errors, and teams that want error mapping covered by tests rather than by convention.
• Use cases that don't: internal tools, server-rendered apps with few JSON endpoints, or products where the error payload is not a customer-facing contract.

When to Consider This Package

Adopt (or spike) when most of these hold:

• You ship a JSON API consumed by clients you don't control (mobile, SPA, partners), and error shape consistency is a real support cost.
• You have many exception types — roughly a dozen or more — where a central switch/match in the handler is becoming a maintenance hotspot.
• You want validation failures and domain failures to land in the same response schema; the release notes show dedicated handling for ValidationFailedException and violation-embedding exceptions, which is exactly this need.
• You're comfortable with a small, single-maintainer package and can pin versions.

Look elsewhere or stay with framework defaults when:

• You only need a handful of custom error responses. Laravel's built-in render()/report() on exception classes plus handler configuration is sufficient and adds zero dependencies. Do not add a package to solve three if statements.
• You need API stability guarantees now. This is 2.0.0-rc3. The RC cycle is explicitly rearranging internals (see below), so the public surface is not yet frozen. If you can't absorb a migration in the next quarter, wait for 2.0.0 stable.
• You extend internals. rc3 consolidates a single formatter for ValidationFailedException and ViolationsEmbeddedException and moves Validator/UID integration code into an Integration\ namespace. If your code imports those classes or subclasses the old formatter, plan for import updates. If you only use the documented entry points, impact is likely nil — verify before upgrading.
• You need vendor support, SLAs, or broad ecosystem mindshare. This is a focused utility; treat it as a dependency you may one day own, and keep your mapping definitions thin enough to port.
• Your error needs are primarily observability (grouping, alerting, breadcrumbs) — that's Sentry/Telescope territory, not this.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our API's error responses are currently inconsistent — each endpoint invents its own failure shape, which costs us client-side bugs, slower partner onboarding, and support time. This package gives us one declarative place to define how every failure is reported, at the cost of a single small dependency. It is low-effort, low-risk, and reversible: our error definitions stay ours, and we can remove the package without rewriting business logic. Recommended action is a timeboxed spike now, adoption after the 2.0 stable release.

For engineering: This is a declarative exception→response mapping layer, Laravel-native, with first-class handling for validation failures and embedded violation lists — the two cases where our current handler is messiest. The new 2.0.0-rc3 is refactor-only: one unified formatter for validation-failed and violations-embedded exceptions, and Validator/UID integration code relocated under an Integration\ namespace. No new features, no deprecations, no documented behavior changes. Practical guidance: pin the exact RC, keep our mapping definitions in application code rather than extending package internals, and budget a short import-path cleanup if we were reaching into Integration-adjacent classes. Upgrade to stable 2.0.0 when it lands and treat that as the point where we commit.