Api Problem Laravel Package

Technical Evaluation

Architecture fit

crell/api-problem is a focused, framework-agnostic implementation of RFC 9457 (formerly 7807) Problem Details for HTTP APIs. It ships immutable value objects (Problem, ApiProblem, ProblemException) and PSR-7/PSR-15 integrations. That is a deliberately narrow surface area — which is good for a Laravel codebase only if we treat it as a serialization contract, not as an HTTP layer.

The core fit question is not "does it work with Laravel" (it does, nominally) but "where do we anchor it." Two viable anchors:

1. Value-object-only adoption — use Problem/ApiProblem as the canonical error DTO inside our own exception renderer. No PSR-7, no PSR-15. This is the low-risk, high-value path.
2. PSR-15 middleware adoption — pull in psr/http-message, psr/http-server-handler, and a Symfony PSR-7 bridge to run Crell's middleware inside Laravel's pipeline. This adds a parallel HTTP abstraction that fights Laravel's Request/Response lifecycle and Octane's request handling.

For a Laravel stack, option 1 is the only defensible default. The package's ProblemException does not extend Illuminate's exception contract, so Laravel's handler will not render it without an explicit mapping. That mapping is small, but it must be owned.

Integration feasibility

Straightforward, with caveats:

• PHP requirement is 8.1+ on current releases — compatible with Laravel 10/11 targets.
• No conflicts with illuminate/*; the package is additive.
• We need a custom renderable exception (or a render() method on a base exception) that returns an Illuminate\Http\Response with Content-Type: application/problem+json.
• Content negotiation (the Accept header check) is our responsibility in Laravel — the package will not inspect Accept for us outside its PSR-15 middleware.

Technical risk

• Low code risk. Small, readable, MIT-licensed, authored by a well-known PHP community maintainer (Larry Garfield). The spec is stable; RFC 9457 is a refinement, not a rewrite.
• Moderate ecosystem-signal risk. 249 stars and effectively zero recorded dependents is a real datapoint. It means limited third-party battle-testing, not bad code. We should treat it as a "vendor-adjacent" dependency and be prepared to vendor or fork.
• Bus-factor risk. Effectively single-maintainer. For a library this small, a vendored copy is a viable contingency.
• Spec-leakage risk. Problem Details encourages exposing a type URI and human-readable detail to clients. Without discipline, internal exception messages (SQL errors, stack traces, tenant IDs) leak into detail. This is a governance risk, not a library risk.
• Scoring context. The aggregate score of 1.875 and opportunity of 29.7 reflect adoption/traction, not capability. A TPM should read that as "under-adopted, technically sound" and size the integration accordingly.

Key questions

1. Do we have external API consumers who will benefit from RFC 9457 compliance, or is this internal-only? If internal-only, the value is largely aesthetic.
2. Is there an existing error envelope convention (e.g., { "error": { "code": ..., "message": ... } }) that clients already parse?
3. Are we already running any PSR-7/PSR-15 components (Octane, RoadRunner, third-party middleware)? If not, adding them just for this is over-engineering.
4. What is our target PHP minimum, and does the pinned version of crell/api-problem align?
5. Do we have a plan — and an owner — for a type URI registry (documentation site, versioning, deprecation)?

Integration Approach

Stack fit

• Laravel 10/11, PHP 8.2+ target. The package's value objects are compatible with zero friction.
• Do not adopt the PSR-15 middleware path unless the stack already carries PSR-7/15 (e.g., a RoadRunner or Swoole deployment). The bridge cost outweighs the benefit inside a standard FPM/Octane Laravel app.
• Use the package as the schema authority: our custom exception renderer serializes through Problem/ApiProblem to guarantee spec-correct output.

Migration path

Phased, opt-in, reversible:

1. Spike (1 sprint). Install in a branch, wire a single custom exception through Problem serialization, and emit application/problem+json from one non-critical endpoint. Validate with existing API contract tests and a consumer smoke test.
2. Opt-in base exception. Introduce App\Exceptions\ApiProblemException extending RuntimeException and implementing Illuminate\Contracts\Support\Responsable, rendering via the package. New endpoints use it; existing endpoints are untouched.
3. Response macro. Add a response()->problem(...) macro wrapping the value object, so controllers can return problems without throwing where a throw is inappropriate (e.g., validation warnings, partial results).
4. Global handler mapping. Extend App\Exceptions\Handler to map ValidationException, AuthenticationException, ModelNotFoundException, and HttpException into Problem Details. This is the moment where the API's error contract actually changes — gate it behind an API version bump.
5. Deprecation of legacy envelope. Only if consumer analytics support it. Otherwise, run dual envelopes by route group.

Compatibility

• Pinning: lock to a specific minor; the package is semver-tagged but pre-2.0 releases have shifted namespaces historically (Crell\ApiProblem vs later ApiProblem\). Verify the exact namespace at install time.
• Octane: safe — the value objects are per-request and stateless.
• No conflict with Laravel's exception handler; the package is additive.
• Test matrix should include: content-type header assertion, type URI resolution, instance field population, nested title/detail separation, and 4xx vs 5xx masking.

Sequencing

Spike → base exception → response macro → global handler mapping → type registry documentation → consumer contract tests → API version gate → rollout.

Each step is independently valuable and independently revertible. That is the property that makes this package attractive despite its low score.

Operational Impact

Maintenance

• Dependency footprint is small and stable; expect near-zero churn from the spec side.
• Upstream release cadence is low and irregular. We should assign an explicit reviewer (likely a senior backend engineer) to watch the repo and pin deliberately.
• Contingency: because the library is ~a few hundred lines of value objects, a vendored fork in app/Support/ProblemDetails is a realistic fallback if upstream stalls. Document this contingency; it lowers the perceived risk from 249-star dependency to "self-owned code."

Support

• No commercial support. Community-only via GitHub issues.
• Internal support burden is on the contract, not the library: on-call engineers need a runbook mapping exception classes to problem type URIs, and a policy for what goes in detail versus what gets logged only.
• Recommend a short internal ADR capturing the package choice, the chosen integration path (value objects only), and the fork criteria.

Scaling

• Negligible runtime cost: value objects, no IO, no caching, no reflection in the hot path.
• Octane-safe; no static state to leak between requests.
• The real scaling concern is contract scaling — as the number of type URIs grows, so does the need for a registry and documentation site. That is a product/docs cost, not a runtime cost.

Failure modes

• Information leakage. Exceptions with sensitive detail reaching clients. Mitigation: a renderer that masks detail for 5xx and for any exception not explicitly allowlisted.
• Content-type mismatch. Clients or gateways rejecting application/problem+json; some CDNs and legacy clients only accept application/json. Mitigation: verify with gateway config; consider a fallback header toggle during transition.
• Contract regression for existing consumers. Laravel's default { "message": ..., "errors": ... } disappearing is a breaking change. Mitigation: route-group scoping and an API version bump.
• Unhandled exception bypass. crell's ProblemException thrown but not mapped in Laravel's handler → generic 500 with Laravel's default shape, silently violating the new contract. Mitigation: a render() method on the base exception, plus a contract test that asserts every thrown ApiProblemException in the test suite renders as application/problem+json.
• Namespace drift on upgrade. Historical namespace changes mean a careless composer update breaks imports at compile time (loud, not silent) — acceptable failure mode.

Ramp-up

• For engineers comfortable with PSR standards: under a day.
• For Laravel-only engineers: roughly a sprint to internalize the spec vocabulary (type, title, status, detail, instance) and the difference between "problem" and "exception."
• Largest ramp-up cost is not the library — it is agreeing on the type URI taxonomy and the masking policy. Budget product/API-design time for that, not engineering time.

TPM verdict

Adopt as a value-object schema authority, not as an HTTP middleware. The low score reflects adoption, not quality; the package is small, spec-correct, and cheaply forkable, which materially de-risks the bus-factor concern. The real integration risk sits in our exception handler and our error-contract governance, both of which we control. Reject the PSR-15 middleware path unless the stack already carries PSR-7/15.