- What does the laravel-api-problem package actually do?
- It maps Laravel's exception rendering pipeline onto the RFC 9457 problem details contract, so failed API requests return a structured JSON body with type, title, status, detail, and instance members instead of Laravel's default error shape. It is a presentation-layer concern only: no domain coupling, no persistence, and no queueing, just a service provider that hooks into the exception handler. The payoff is a stable, machine-readable error contract that web, mobile, and third-party clients can parse the same way.
- How do I install pedrosalpr/laravel-api-problem in a Laravel app?
- Install it with Composer using composer require pedrosalpr/laravel-api-problem, then publish any shipped configuration with php artisan vendor:publish and pick the package's provider tag. Registration follows the usual Laravel package conventions, so there are no migrations or extra services to stand up. Review the published config and the package source before enabling it, since the source is small enough to read end to end in one sitting.
- Which Laravel and PHP versions does this package support?
- Check the require and require-dev blocks in the package's composer.json for the exact Laravel and PHP constraints, because that file is the authoritative support matrix. The intended target is standard PHP 8.x applications on Laravel 9, 10, or 11 serving JSON APIs. Also confirm whether the maintainer's CI actually runs against the specific Laravel version you pin before rolling it out.
- Does it override error responses globally or can I enable it per route group?
- The package integrates at the exception handler and service provider level, which means a global registration changes the status codes, media type, and body shape of every error response in the application. That is effectively a breaking API change for existing consumers, so treat it as opt-in until you have verified the behavior. Test against a single new or versioned route group first and confirm whether the package can be scoped via middleware before enabling it application-wide.
- Does it convert Laravel ValidationException 422 errors into problem details?
- Validation failures are the highest-volume 4xx class in most Laravel APIs, so this is the coverage question that determines whether your error contract is genuinely uniform. Verify that ValidationException is normalized into a problem document with the field errors exposed as an extension member rather than falling through to the default handler. If it is not covered, add your own render hook so 422s match the rest of your problem responses.
- Which HTTP errors are covered, such as 401, 403, 404, 405, 419, 429, and 500?
- You should confirm coverage for 401, 403, 404, 405, 419, 422, 429, 500, and unhandled Throwable instances explicitly, since gaps tend to show up in authentication and CSRF paths first. The package is built to render Laravel exceptions as problem documents, but the exact mapping lives in its rendering logic and any published config. Write contract tests for each status your clients depend on so a missing mapping fails loudly instead of silently returning a different envelope.
- Will debug details or stack traces leak into production error responses?
- This is the highest-severity failure mode for any problem details renderer: detail, instance, and any debug or trace extension members must be gated on app.debug and never emitted in production. Review the rendering code to confirm the gate exists and test it with APP_DEBUG=false and APP_DEBUG=true in separate environments. If the package does not gate them itself, wrap or override the renderer so internals cannot escape.
- How do I customize problem type URIs, extension members, and error titles?
- Custom type URIs, extension members, and per-exception titles are typically exposed through the published config file or by extending the package's problem class, so check the config and source for the supported seams. Laravel's translator can be used for title and detail strings if the package routes them through __(), which makes localization possible for multi-locale APIs. Keep your type URIs stable and documented, since clients often branch on the type member.
- Does it return application/problem+json and honor the Accept header?
- RFC 9457 specifies the application/problem+json media type, so verify the package sets it exactly and not a generic application/json, and confirm whether it negotiates on Accept or always returns problem+json. If your API sits behind a gateway or CDN that inspects or rewrites Content-Type, test the full path end to end. Clients with strict parsing will break if the media type or body shape changes between routes.
- Is laravel-api-problem safe to depend on in production, or should I fork it?
- It has a small adoption footprint and a single maintainer, so bus factor and abandonment are the dominant risks and usually surface as a blocker on the next Laravel major upgrade. Mitigate by pinning the version, reading the source, and keeping a thin internal adapter or mapping layer so a fork or reimplementation is a swap rather than a rewrite. The package surface is small, so a clean fork is viable if you check the license and contribution posture first.