- How do I install laravel-api-response-builder in a Laravel app?
- Install it with Composer using composer require marcin-orlowski/laravel-api-response-builder. The service provider is auto-discovered, so no manual registration is normally needed. Publish the config file with php artisan vendor:publish so you can tune defaults, and optionally register the facade alias if you prefer the static ResponseBuilder style. Adoption is low-friction and requires no schema or infrastructure changes.
- Which Laravel and PHP versions does laravel-api-response-builder support?
- The supported matrix is defined in the package's composer.json and release notes, so check it against your Laravel and PHP targets before committing. This matters most on Laravel 11 and newer, where exception handling moved to bootstrap/app.php with withExceptions(). A version gap there can block adoption entirely, so pin a release you have verified rather than relying on the latest tag.
- Should I use the ResponseBuilder facade or the ApiResponse contract?
- The package has historically offered both a static ResponseBuilder facade and a DI-friendly ApiResponse contract. The injectable contract is generally the safer long-term choice because it keeps controllers testable and avoids depending on a path that may be deprecated. Pick one style up front and standardize on it, since mixing both makes the codebase harder to migrate later.
- How do I map custom error codes to HTTP statuses?
- You define business error codes by implementing the package's ApiCode interface, mapping each internal code to an HTTP status and a message. Those implementations become a shared error taxonomy that backend and client teams can both reference. Keep the registry small and documented, and treat adding a new code as an API change rather than an internal refactor.
- Does laravel-api-response-builder handle validation errors and uncaught exceptions?
- The package standardizes the JSON envelope, but you still need to wire it into Laravel's exception handler so validation failures and uncaught exceptions render through the same builder. Without that, ValidationException and other errors can produce a different shape or a duplicate envelope. Add a renderable in your handler and write contract tests that freeze the error output.
- Can I nest Eloquent API Resources inside the response data?
- Yes. The package operates purely in the presentation layer and does not interfere with your domain or persistence code, so Eloquent API Resources can be nested inside the data key. This lets you keep using Laravel's resource transformations while still returning one predictable envelope. The envelope itself is an opinionated contract, so decide on it before clients ship against your API.
- Does it support translated or localized API messages?
- Yes, localization is supported through Laravel's translation layer, which is a real differentiator for multi-locale products. The trade-off is hidden overhead: you must manage translation keys for every code and message in each locale. Set conventions for those keys early so missing translations do not silently fall back to raw identifiers in client-visible responses.
- What happens with APP_DEBUG=true, does it leak stack traces in API errors?
- Whether debug output leaks depends on how you configure the exception handler alongside the package, so test it explicitly rather than assuming. Verify that internal exception messages and traces are suppressed in the errors payload for production-like responses. A quick integration test with APP_DEBUG toggled on and off is the cheapest way to confirm you are not exposing internals.
- Can I disable the envelope for specific routes like webhooks or health checks?
- Adding the envelope is a hard-to-reverse, client-facing decision, so third-party callbacks and health checks that expect bare payloads need special handling. Confirm whether your pinned version exposes a per-route opt-out before you commit, and if not, keep those endpoints outside the builder. Document the exceptions so the API does not end up with an inconsistent shape by accident.
- Is laravel-api-response-builder actively maintained, and what are the alternatives?
- It is effectively a single-maintainer package with around 852 stars and few recorded dependents, which is a weak adoption signal, so budget for the contingency of vendoring or forking. Ask about release cadence and whether an upgrade guide exists between majors before pinning. If your clients already mandate a spec, JSON:API, HAL, or plain payloads with HTTP status semantics may fit better than an opinionated envelope.