Weave Code
Api Problem Laravel Package
phpro/api-problem
A framework-agnostic RFC 7807 Problem Details implementation for PHP, providing an interface, an ApiProblemException, and built-in HTTP problem types (400–428) for consistent API error responses, with Symfony integration available.
phpro/api-problem provides an RFC 7807 Problem Details implementation for PHP APIs, offering a consistent way to represent HTTP error responses. It is framework-agnostic and includes a generic interface, an ApiProblemException, and ready-to-use problem classes for common HTTP statuses such as 400, 401, 403, 404, 405, 409, 422, and more.
- RFC 7807 compliant problem detail value objects
- Framework-agnostic design with Symfony bundle integration
- Built-in HTTP problems and ExceptionApiProblem for debug output
- Simple exception-based throwing and consistent API error formatting
Frequently asked questions about Api Problem
- How do I install phpro/api-problem in a Laravel application?
- Install it with Composer using composer require phpro/api-problem. The package has no Laravel service provider or config file, so you wire it into your app manually. Use it from App\Exceptions\Handler or from API middleware to return RFC 7807 responses.
- Does phpro/api-problem have built-in Laravel support?
- No, the core package is framework-agnostic. It provides the RFC 7807 interface, ApiProblemException, and built-in HTTP problem types, while the only official framework bundle mentioned is for Symfony. Laravel integration is done through your exception handler, middleware, or a small adapter layer.
- How do I return RFC 7807 errors from Laravel's exception handler?
- Override or extend the render method in App\Exceptions\Handler so API exceptions are converted into ApiProblem objects and returned as JSON with the application/problem+json content type. Keep web and API error handling separate so HTML routes are not affected. Centralize the mapping to avoid conflicting with Laravel's default exception rendering.
- Can I use ValidationApiProblem with Laravel FormRequest validation?
- Yes, but you need to map Laravel validation failures into the violation structure ValidationApiProblem expects. The package's validation problem is built around Symfony validator violations, which can be used alongside Laravel's validation system. Version 1.10.0 also lets you pass a custom status code so FormRequest failures follow your API contract.
- How do I change the validation error status code in phpro/api-problem 1.10.0?
- ValidationApiProblem now accepts an explicit status code, so you can return 400, 422, 409, or another agreed code instead of always using the default 422. This is an opt-in, backward-compatible change. Document the chosen convention in your OpenAPI schema and apply it consistently across endpoints.
- How should I handle debug details and stack traces in production with phpro/api-problem?
- Use the package's debug-aware problem types only when debugging is enabled, such as when APP_DEBUG is true. ExceptionApiProblem adds exception details only in debug context, but you should still redact sensitive database or internal errors. Never expose stack traces or debug payloads in production API responses.
- Is phpro/api-problem compatible with modern Laravel versions and PHP 8.1?
- The package supports PHP 8.1+ and is framework-agnostic, so Laravel applications on supported PHP versions can use it. There is no Laravel-specific version constraint in the core package, but test Composer dependency conflicts, especially around symfony/validator. Run integration tests against your exact Laravel release before rollout.
- How do I standardize all Laravel API error responses with phpro/api-problem?
- Use an API-focused exception renderer or middleware that catches exceptions and converts them into ApiProblem instances. Return the matching HTTP status code and application/problem+json content type consistently. Keep this scoped to API routes and test legacy error formats if backward compatibility matters.
- What built-in HTTP problem types does phpro/api-problem provide?
- It includes problems for common HTTP errors such as BadRequestProblem, UnauthorizedProblem, ForbiddenProblem, NotFoundProblem, MethodNotAllowedProblem, ConflictProblem, PreconditionFailedProblem, UnsupportedMediaTypeProblem, IAmATeapotProblem, UnprocessableEntityProblem, LockedProblem, and PreconditionRequiredProblem. It also provides HttpApiProblem and ExceptionApiProblem for more general cases. These map directly to Laravel HTTP responses when rendered from your handler.
- How do I create custom domain-specific problem types with phpro/api-problem?
- Implement ApiProblemInterface or build on the provided problem classes to define your own status, type, title, detail, and extension fields. Register the mapping in your Laravel exception handler or middleware so domain exceptions become consistent RFC 7807 responses. For nested validation errors, define and document a stable structure before exposing it to API consumers.
Weaver
How can I help you explore Laravel packages today?