Unified REST API Response formatter for Laravel

LaravelApiResponse is a Laravel package for building consistent and well-structured REST API JSON responses. Includes automatic exception handling, module-aware localization, structured logging, and pagination out of the box.

Available in other languages: RU

Table of contents

• Introduction
• Requirements
• Installation
• Quick start
• Features
• Design principles
• Documentation
• Changelog
• License

Introduction

Every Laravel API developer has hit the same wall: an exception fires, and instead of JSON your client gets a wall of HTML. laravel-api-response fixes that — and while it's at it, gives every response a consistent, predictable structure your frontend can always rely on.

Every response carries a structured message object with a machine-readable key and a human-readable gui string resolved from your translation files. Errors additionally include a sys field for internal context.

Success response example:

{
    "success": true,
    "http_code": 201,
    "http_text": "Created",
    "message": {
        "key": "user.created",
        "gui": "User created successfully"
    },
    "meta": null,
    "data": {
        "id": 42,
        "email": "user@example.com"
    }
}

Error response example (including exceptions — always JSON, never HTML):

{
    "success": false,
    "http_code": 422,
    "http_text": "Unprocessable Content",
    "message": {
        "key": "user.unprocessable_content",
        "gui": "Validation error",
        "sys": "The email field is required"
    },
    "details": {
        "fields": {
            "email": ["The email field is required."]
        }
    }
}

data and details are mutually exclusive — data and meta appears in success responses, details in errors. meta is null for simple responses and carries pagination data when the response is paginated.

Requirements

Installation

1. Require the package:

composer require src83/laravel-api-response

2. Run the installer:

php artisan api-response:install

The installer adds some things and modifies others in your existing project. You can review these targeted changes by running git status after executing the installation command.

In particular, pay close attention to Handler.php and Authenticate.php.

This package can be installed both on a fresh Laravel application and on an existing project with substantial business logic and a customized exception handler.

Depending on the project, the installer may behave differently (adaptively):

• In a new, clean Laravel project, these two files will be fully updated during installation. However, they still require a quick review before you accept the changes. Once the installation is complete, you can immediately proceed to the next step Verify the installation to make sure the package was installed correctly.

• When installing the package into a more mature project, Handler.php and Authenticate.php may not be updated immediately if the installer detects that they already contain customized logic. Such items will be marked as ACTION REQUIRED. This is normal behavior. In any case, proceed to the next step Verify the installation.

3. Verify the installation:

php artisan api-response:check

Confirms that all components have been installed correctly.
If anything shows ACTION REQUIRED, the installer detected existing custom logic in that file and did not overwrite it automatically.

In this case:

• Back up the files marked ACTION REQUIRED;
• Force-update them by running:

  php artisan api-response:check --fix
  

• Manually resolve any conflicts between the existing and new logic in the updated files.

That's it — the package is installed and ready to use.
You can run php artisan api-response:check one more time to confirm, then get to the fun part.

Quick start

use Src83\LaravelApiResponse\Enums\MessageKeyEnum;
use Src83\LaravelApiResponse\Http\Responses\ApiErrorResponse;
use Src83\LaravelApiResponse\Http\Responses\ApiSuccessResponse;
use Symfony\Component\HttpFoundation\Response;

// List — no messageKey needed
return ApiSuccessResponse::make(data: UserResource::collection($users));

// Store
return ApiSuccessResponse::make(
    data: new UserResource($user),
    httpCode: Response::HTTP_CREATED,
    messageKey: MessageKeyEnum::CREATED,
);

// Error
return ApiErrorResponse::make(
    httpCode: Response::HTTP_NOT_FOUND,
    messageKey: 'user.not_found',
    sysMessage: $e->getMessage(),
);

For a full reference — call signatures, response shapes, and pagination — see the docs/api-contract.md

Features

• Consistent JSON contract — every response, including exceptions, returns the same structure
• Exception → JSON — HTTP and domain exceptions are caught and rendered as structured errors, never as HTML
• Module-aware localization — gui messages are resolved from lang/{locale}/api_response.php by module and key
• Pagination — built-in ApiPaginator for Eloquent paginators and ArrayPaginator for plain arrays
• Structured logging — separate channels for throwable errors, rendered errors, missing translations, and business warnings
• Middleware stack — ForceAcceptJson, BindRequestContext (request ID), WrapApiResponse, AppendExecutionTimeMeta, ForceContentType
• Execution time — optional meta.execution_time field for diagnosing slow endpoints
• Artisan commands — api-response:install and api-response:check [--fix]
• Built-in exceptions — DomainLayerException and ItemNotFoundException ready to throw from your domain layer
• Request macros — $request->isApi() and $request->apiModule() available out of the box
• Standard action vocabulary — MessageKeyEnum covers all common CRUD and status keys

Design principles

• Controllers don't build messages — they pass a messageKey, the package resolves the translation
• messageKey can be a MessageKeyEnum value, a plain string, or a compound module.key
• The module is derived automatically from the route prefix — no manual configuration needed per endpoint
• All exceptions speak the same JSON — no special cases, no HTML leaking through

Documentation

The essentials are covered in this README. Full documentation is in progress — for details, browse the inline code comments or open an issue.

• Installation → docs/installation.md
• API reference (contract + usage examples) → docs/api-contract.md
• Configuration reference → docs/configuration.md
• Localization → docs/localization.md
• Logging → docs/logging.md
• Exception handling → docs/exceptions.md

License

• Written and copyrighted © 2026 by Roman Staroseltsev
• Open-source software licensed under the MIT license
• Author: LinkedIn