Laravel Api Problem Laravel Package

Product Decisions This Supports

• API error contract standardization. The package renders exceptions as RFC 7807/9457 application/problem+json payloads, so every service in the Laravel estate can emit one predictable error shape instead of ad-hoc {message, errors, code} variants. This is a contract decision, not an implementation detail — it affects SDKs, public docs, partner integrations, and support runbooks.
• Build vs. buy for the error layer. Replacing it means writing and maintaining a custom exception renderer, content negotiation for application/problem+json, type/instance/status mapping, and validation-error flattening — roughly a few hundred lines plus ongoing Laravel upgrade upkeep. Adopting the package converts that into a config file and a dependency review.
• Roadmap input for public/partner-facing APIs. If the roadmap includes external consumers, mobile clients, or anything under a published OpenAPI spec, problem details should land before the first external contract is frozen. Retrofitting an error format post-GA is a breaking change for every consumer.
• Support and observability cost. Machine-readable type URIs give support and on-call a stable key to grep, alert on, and link to documentation — a measurable reduction in triage time versus free-text messages.
• Multi-service consistency. A shared error dialect is a prerequisite for a gateway/BFF, a unified SDK, or any client that speaks to more than one Laravel service. Choosing per-service formats quietly creates a client-side translation layer you will own forever.

When to Consider This Package

Consider adopting when:

• You run one or more Laravel HTTP APIs consumed by parties you don't control (partners, mobile apps, third-party developers) or by multiple internal teams.
• You are already publishing or plan to publish an OpenAPI/JSON Schema contract and want error responses described in it rather than omitted.
• Your current error handling is inconsistent — different controllers, form requests, and exception types returning different shapes — and a normalization pass is cheaper than a rewrite.
• You want the standard for near-zero marginal cost: it is a thin layer over Laravel's exception handler with a publishable config, and the effort is largely mapping your domain exceptions to problem types.

Look elsewhere or build in-house when:

• The stack isn't Laravel (Symfony has comparable primitives; other frameworks need different plumbing).
• The API is internal-only and single-consumer — a consistent {message, errors} convention plus a lint rule gets you most of the benefit without a dependency.
• You need GraphQL or gRPC error semantics; problem details is an HTTP/JSON-shaped answer and maps awkwardly onto those transports.
• You require a vendor with a support contract, SLA, or security-review paperwork. This is a small, single-maintainer package in the API Skeletons family — low activity, narrow scope, and no commercial backing. Assess bus-factor risk honestly; the compensating factor is that the surface area is small enough to fork or vendor if it is ever abandoned.
• You need guarantees on a long support window across a wide PHP/Laravel matrix. Verify against your versions before committing.

On 2.0.1 specifically: this is a dependency-only patch — it moves instantiator to 2.0 and nothing else. Treat it as routine hygiene, not a capability change. Two things to confirm before bumping: (1) instantiator 2.0 raises the PHP floor, so re-check it against your oldest supported runtime; (2) nothing in 2.0.0's API changed, so no application code or config migration is implied. If you are not already on 2.0.x, note that the 1.x → 2.0 jump is where the real review effort sits, not here. Pin the version and let your normal dependency-update cadence absorb it.

How to Pitch It (Stakeholders)

To executives: Our APIs currently describe failures differently depending on which endpoint you call. External consumers have to special-case our errors, which shows up as integration support load and slows partner onboarding. This package moves us onto the industry-standard error format (RFC 7807) used across the wider API ecosystem, at the cost of a config file and an exception mapping exercise rather than a custom build. It makes our error surface documentable and contract-testable, and it is the cheaper half of "should we standardize our API responses" — the success path can follow later using the same pattern.

To engineering: It's a small, focused Laravel package that hooks into the exception handler and emits application/problem+json with type, title, status, detail, and instance, plus extensible custom members. Adoption is mostly mapping our existing domain exceptions to problem types and deciding the type URI namespace — that namespace is the durable decision, so get it right the first time. The 2.0.1 release is a dependency bump only, no code changes; the one thing to check is the raised PHP floor from instantiator 2.0 against our supported runtime matrix. Risk is vendor size, not complexity: it's a single-maintainer package, but the surface is small and forkable, so we can pin it and keep a vendored escape hatch. Recommend a spike on one service, ship behind the existing error contract, and expand if triage and partner feedback support it.