Api Problem Bundle Laravel Package

Product Decisions This Supports

• API error contract as a product surface. RFC 7807 (Problem Details) is a published, language-agnostic standard. Deciding to adopt it is a product decision about the developer experience your API sells, not just an implementation detail. This package is a reference implementation of that decision, useful primarily as evidence that the pattern is small enough to standardize across every endpoint.
• Developer-facing roadmap bets. If your roadmap includes a public API, partner integrations, a developer portal, or client SDKs, a uniform machine-readable error format is a prerequisite. It lets clients write one error handler instead of N, which compounds across every consumer you onboard.
• Build vs. buy, resolved toward "borrow the spec, build the adapter." Because the artifact is archived (last release 2019, zero dependents, Symfony-coupled), the defensible PM call is to adopt the standard and not the package. Scope a one-to-two sprint internal slice — exception-to-problem+json mapper, validation-error normalizer, stable type URI catalog — behind a small internal interface. That keeps you spec-compliant while owning the maintenance.
• Prioritizing an error taxonomy. Adopting Problem Details forces a named, documented set of type values and extension fields. That is a genuine product artifact: an error catalog is what makes support triage, client retry logic, and documentation coherent. Use this package's extension model as the design template even if the code is discarded.
• Use cases it fits: internal service-to-service APIs, validation-heavy CRUD surfaces, regulated or standards-sensitive integrations, and any product where third parties write the client code.
• Use cases it does not decide: anything needing active vendor support, framework-native (Laravel) middleware ergonomics, or long-term maintenance guarantees.

When to Consider This Package

Consider the pattern — and evaluate this code — when:

• You are a Symfony shop (the package is a Symfony bundle; the Laravel framing in the brief is inaccurate and should be corrected before it reaches engineering). Framework mismatch alone disqualifies direct reuse for a Laravel codebase; the concept transfers, the bundle does not.
• Your API has multiple heterogeneous clients or external integrators, so error-format inconsistency is already generating support load.
• You have validation-heavy endpoints and want one code path for both exceptions and validation failures.
• You need a small, auditable reference for how Problem Details maps onto an existing exception hierarchy — reading it is cheaper than designing from scratch.
• The blast radius is contained: a spike, an internal API, or a prototype where a pinned pre-1.0 dependency is acceptable.

Look elsewhere (or build in-house) when:

• You are on Laravel — use a maintained Laravel-native equivalent or a thin internal middleware; do not port a 2019 Symfony bundle.
• The dependency sits on a critical, customer-facing path with an SLA. Archived, zero-star, zero-dependent, no security policy, no release cadence since 2019: unacceptable as a committed platform dependency.
• You require active maintenance, CVE response, or framework-version currency (current Symfony/PHP versions are almost certainly unsupported).
• The requirement is only "consistent errors" and a ~150-line internal implementation plus a documented error catalog satisfies it — that is the cheaper, lower-risk path nearly every time.

Adoption criteria if a spike proceeds: pin the exact version, isolate behind an internal adapter, verify PHP/Symfony constraints against your platform, confirm the logging behavior added in v0.2.0 is configurable and PII-safe, and schedule a review with a predefined trigger to replace it.

How to Pitch It (Stakeholders)

To executives (one paragraph): Our API's error responses are an under-managed part of the product. Today every failure looks slightly different, which pushes cost onto our customers' engineers and onto our support team. There is a published internet standard, RFC 7807, for exactly this. A small open-source package implements it, but it is archived, unmaintained, and built for a framework we do not use — so the recommendation is to adopt the standard and build a thin internal implementation rather than take the dependency. Expected outcome: faster client integration, fewer "what does this error mean" tickets, and a documented error catalog we control. Cost is roughly one to two sprints of engineering, and risk is low because the format is a public standard — if we later change implementation, clients see no difference.

To engineering (summary): We are standardizing API error payloads on application/problem+json. Do not vendor libero/api-problem-bundle: it is Symfony-only, last released February 2019, archived, and has zero dependents and no security policy. Treat it as a design reference. Deliver a framework-native middleware that (1) maps domain exceptions to Problem Details with a stable type URI per error class, (2) normalizes validation failures into a consistent errors extension, (3) allows custom extension members without breaking the base shape, and (4) logs with a Laravel/Symfony-native logger — sanitized, level-configurable, and never blocking the response. Keep the implementation behind an internal interface so the transport format is swappable, ship the error catalog alongside it, and add contract tests that assert the wire format per endpoint. One spike, then a staged rollout behind a feature flag.

To support and docs: this gives you a single structured artifact to document and triage from — error type, human-readable title, and a canonical link. Treat the error catalog as a first-class docs deliverable, not an afterthought.