Download the PHP package imran/laravel-api-toolkit without Composer

Laravel API Toolkit

Standardized JSON API responses and an automatic, environment-aware exception handler for Laravel APIs — built for teams shipping a REST/JSON API to a frontend (Next.js, Vue, mobile, etc.) that needs one predictable response shape, always.

• A clean ApiResponse facade/trait: ApiResponse::success($data), ApiResponse::error($message, $code), ApiResponse::loading(), and more.
• Zero-config exception normalization: validation errors, ModelNotFound, auth/authorization failures, 404/405/429, and uncaught 500s are all automatically converted into the same JSON envelope — no changes to your Handler.php or bootstrap/app.php required.
• Validation errors are flattened into a frontend-friendly field/message array by default (configurable back to Laravel's native nested shape).
• Environment-aware: stack traces and exception details are only ever included when APP_DEBUG (or the package's own debug flag) is on.
• A typed ApiException you can throw directly from domain/business code (throw ApiException::notFound('Order not found.')) with its own status/error_code/structured errors/headers.
• Paginators passed into success() are automatically unwrapped into data + meta.pagination — no manual reshaping needed.
• Custom/domain exceptions mapped via exception_map can carry their own structured errors array, and HTTP headers an exception carries (Retry-After, Allow, ...) are preserved onto the normalized response.

Installation

The service provider and ApiResponse facade are auto-discovered. Publish the config (and optionally the language file) if you want to customize anything:

Response contracts

Success

meta is omitted entirely when empty.

Error

errors is omitted when not applicable. With api-toolkit.debug enabled, error responses also include a debug key (exception, file, line, and trace if show_trace is on) — but only for genuinely uncaught/unmapped exceptions (the 500 fallback). A mapped/known exception (validation, not-found, your own exception_map/ApiException entries, ...) never gets a debug key regardless of debug mode, since its status/message/error_code are already accurate and self-explanatory — debug exists to help diagnose the unexpected, not to duplicate what's already in the response.

Loading / processing (HTTP 202 — for async jobs / polling endpoints)

Paginated success — pass a paginator straight into success():

Works with LengthAwarePaginator (paginate()), the simple Paginator (simplePaginate() — same shape minus total/last_page/nav.last), and CursorPaginator (cursorPaginate() — next_cursor/prev_cursor instead of page numbers), whether passed raw or wrapped in a Resource collection. Set api-toolkit.paginate to false to disable and pass paginators through untouched.

Usage

Facade

Controller trait

Prefer calling these methods directly on the controller instead of importing the facade everywhere:

The trait uses common names (success, error, created, deleted, forbidden, notFound, ...). If a base controller you're adopting this into already defines one of these itself, PHP will raise a "trait method has not been applied, because there are collisions" fatal error. Alias around it:

Global helpers

Throwing typed API errors: ApiException

For business/domain errors, throw ApiException directly instead of round-tripping through exception_map config:

It self-renders into the standard JSON envelope even if auto_register is disabled (Laravel calls an exception's own render() method when it defines one — this runs before the package's exception_map/built-in mapping, so ApiException always wins regardless of that config). Because of this, ApiException always responds with JSON, even for a request that didn't ask for it — only throw it from API code paths.

By default, report() suppresses Laravel's normal exception logging for expected client errors (status < 500) — the same way Laravel itself already treats ValidationException/ModelNotFoundException — while genuine 5xx errors are still logged as usual. Extend ApiException and override report() if you want different behavior.

Automatic exception handling

The moment the package is installed, any exception thrown while handling a request that expects JSON (or matches config('api-toolkit.paths'), api/* by default) is normalized automatically:

Requests that don't expect JSON and don't match paths are left completely untouched — your normal Blade error pages keep working.

Adding your own exceptions

Map any exception (including your own domain exceptions) in config/api-toolkit.php without writing any handler code:

If a mapped (or built-in) exception defines its own public errors() method — the same convention ValidationException and Illuminate\Contracts\Validation\Validator already use — its return value is used as the response's errors array automatically:

HTTP headers the exception itself carries are also preserved onto the normalized response — e.g. Retry-After on a throttling exception or Allow on a method-not-allowed exception — matching Laravel's own default behavior.

Disabling auto-registration

If you'd rather wire it up yourself (e.g. you already have a heavily customized Handler.php), set:

and call the renderer manually from your own exception handler:

Configuration reference (config/api-toolkit.php)

Message resolution order

For any error response, the message shown is resolved in this order: (1) an explicit $message argument, (2) an exception_map override, (3) the exception's own non-empty message, (4) the status_messages → messages lookup for that HTTP status, (5) the status's standard HTTP reason phrase (e.g. Unprocessable Entity) as the final fallback. A response's message is never empty.

Testing

License

MIT.