Weave Code
Apixception Bundle Laravel Package
pccomponentes/apixception-bundle
A Symfony bundle for consistent API exception handling, turning thrown exceptions into standardized JSON error responses with predictable HTTP status codes. Centralize exception-to-response mapping, reduce boilerplate, and keep API errors uniform across services.
Apixception Bundle
Apixception Bundle by PcComponentes provides centralized exception handling for Symfony APIs, converting thrown exceptions into consistent, structured JSON error responses with appropriate HTTP status codes. It keeps error presentation separate from domain logic, helping API clients receive predictable failures across services.
- Configurable mapping from exception types to HTTP status codes
- Consistent JSON error payloads for API consumers
- Symfony-native bundle integration and configuration
- Extensible support for custom exception handlers
- Sensible defaults for production and debugging environments
Frequently asked questions about Apixception Bundle
- What does pccomponentes/apixception-bundle do?
- It is a Symfony bundle that catches exceptions thrown during request handling and renders them as standardized JSON error responses with appropriate HTTP status codes. It hooks into Symfony kernel events, specifically the exception flow, so controllers and services can throw domain exceptions without formatting error payloads themselves. The result is a consistent error contract across a REST or API-style application. It targets Symfony projects rather than Laravel applications.
- Is apixception-bundle a Laravel package or a Symfony bundle?
- It is a Symfony bundle, published under the pccomponentes vendor name, and it depends on Symfony components such as HttpFoundation and the event dispatcher. It is not a Laravel package and does not register a Laravel service provider or ship Laravel-specific configuration. Laravel developers can still study it as a reference implementation, since Laravel's exception handler solves the same problem using Symfony's HTTP primitives underneath.
- How do I install pccomponentes/apixception-bundle with Composer?
- Run composer require pccomponentes/apixception-bundle, then enable the bundle in config/bundles.php for the environments where you want API-style error rendering. Commit both composer.json and composer.lock so the resolved Symfony versions are reproducible. After installation, check the bundle's README for the exception interface and any configuration you need to publish.
- Which Symfony versions does apixception-bundle 2.1.1 support?
- Release 2.1.1's stated change is allowing Symfony 7.4, which reads as a widened composer.json constraint rather than a code change. That means teams already on Symfony 7.4 can resolve the package without a fork or the ignore-platform-reqs flag. Before relying on it, confirm in the package's composer.json that the lower bound is unchanged and check whether Symfony 7.4 actually appears in its CI matrix. A widened constraint is a compatibility promise, not proof that the combination has been exercised.
- How does apixception-bundle convert exceptions into JSON error responses?
- It listens to Symfony kernel events and intercepts exceptions before the default error handling renders an HTML page. Each exception type is associated with an HTTP status code and a serialized error body, so API clients always receive the same JSON structure. Because the logic sits in the kernel event layer, it applies to every controller and route without per-action try/catch blocks.
- Can I use apixception-bundle in a Laravel application?
- Not directly: it is a Symfony bundle that registers through the Symfony kernel and bundle system, and Laravel does not load bundles that way. Laravel has its own exception handler, and the equivalent behavior is implemented in bootstrap/app.php with the withExceptions callback or a custom render method. If your application is Symfony-based, or you are porting an API between the two frameworks, the bundle's exception-to-status-code mapping is a useful reference.
- How do I map a custom exception to a specific HTTP status code?
- You define an exception class for the error condition and tell the bundle which status code and payload it should produce, following the mapping mechanism described in the package README. In practice you group exceptions by meaning, such as validation failures, not found, authentication, and conflicts, so the status code follows from the exception type rather than from the call site. Keep the JSON body stable across mappings so clients can parse errors reliably.
- How do I resolve Composer conflicts after apixception-bundle allows Symfony 7.4?
- Run composer why-not symfony/framework-bundle 7.4 and composer why-not symfony/http-foundation 7.4 to identify which packages still pin Symfony below the new floor. Conservative upper bounds in sibling packages are the usual blockers, and they generate the support tickets rather than this bundle. Resolve in a branch, run composer update pccomponentes/apixception-bundle --with-dependencies, and review the lockfile diff as the artifact under review. If the host application's Laravel version does not yet ship Symfony 7.4, the update is inert and can wait.
- How should I test API error responses in a Symfony or Laravel app?
- Write feature tests that call endpoints with inputs designed to trigger each exception type, then assert both the HTTP status code and the JSON error shape. Assert the contract, not the exact message text, so wording changes do not break the suite. For Symfony, use the KernelBrowser or an HTTP client against a test kernel; for Laravel, use the built-in HTTP test helpers and assertJsonStructure. Add one test per mapped exception class so new mappings cannot silently regress.
- What are the alternatives to apixception-bundle for API error handling?
- In Symfony, the built-in error listener with a serializer, API Platform's error handling, or a small custom kernel.exception listener all cover the same ground. In Laravel, the framework's exception handler with render or renderable callbacks handles exception-to-JSON conversion without an extra package. Choose based on whether you want a packaged convention or a small amount of application code you fully control. Since apixception-bundle's recent release is a patch-level constraint widening, check the repository's activity and issue tracker before adopting it for a new project.
Weaver
How can I help you explore Laravel packages today?