README

A Laravel package that enforces a consistent API response envelope — success, paginated, error, and bulk partial failure — so all services speak the same shape without hand-rolling ResponseFactory in each one.

Requirements

PHP 8.2+
Laravel 10, 11, 12, or 13

Installation

Option 1 — Composer (recommended)

composer require vandet/laravel-api-response

Laravel auto-discovers the service provider — no manual registration needed.

Option 2 — Clone the repository

Use this when you want to contribute, customise the source, or install without Packagist.

1. Clone into your project

git clone https://github.com/vandet/laravel-api-response.git packages/laravel-api-response

2. Add the local path repository to your composer.json

"repositories": [
    {
        "type": "path",
        "url": "./packages/laravel-api-response"
    }
]

3. Require the package

composer require vandet/laravel-api-response

Composer symlinks the cloned folder into vendor/ — any changes you make to the source are reflected immediately without re-running composer update.

Publish the config (optional)

php artisan vendor:publish --tag=api-response-config

This creates config/api-response.php where you can toggle exception handling per type.

Usage

ResponseFactory

Import once at the top of your controller:

use Vandet\ApiResponse\Http\ResponseFactory;

Success — single resource

return ResponseFactory::success($user, 'User retrieved successfully.');

{ "success": true, "message": "User retrieved successfully.", "data": { ... } }

Success — created (201)

return ResponseFactory::created($user, 'User created successfully.');

Success — accepted async job (202)

return ResponseFactory::accepted('Import queued successfully.');

Success — paginated collection

Pass a Laravel LengthAwarePaginator directly. Call ->withQueryString() on the paginator to preserve filter/sort params in links.

$users = User::paginate(20)->withQueryString();

return ResponseFactory::paginated($users, 'Users retrieved successfully.');

{
    "success": true,
    "message": "Users retrieved successfully.",
    "data": [...],
    "pagination": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 82, "from": 1, "to": 20 },
    "links": { "first": "...", "last": "...", "next": "...", "prev": null }
}

Success — with reference data

return ResponseFactory::withIncluded($users, [
    'roles'    => Role::all()->toArray(),
    'statuses' => Status::all()->toArray(),
], 'Users retrieved successfully.');

Delete (204 — no body)

return ResponseFactory::deleted();

Validation error (422)

With FormRequest (recommended) — no manual call needed. The exception handler catches the ValidationException that FormRequest throws automatically and converts it to the standard envelope for you.

// FormRequest — just type-hint it, validation + response are automatic
public function store(StoreUserRequest $request): JsonResponse
{
    $dto = UserDTO::fromRequest($request);
    // ...
}

{ "success": false, "message": "Validation failed.", "code": "VALIDATION_FAILED", "errors": { "email": ["Email is required."] } }

With a manual validator — call ResponseFactory::validationError() yourself:

$validator = Validator::make($request->all(), [
    'email' => ['required', 'email'],
]);

if ($validator->fails()) {
    return ResponseFactory::validationError($validator->errors()->toArray());
}

Not found (404)

use Vandet\ApiResponse\Constants\ErrorCodes;

return ResponseFactory::notFound(ErrorCodes::USER_NOT_FOUND, 'User not found.');

Unauthorized (401) / Forbidden (403) / Conflict (409)

return ResponseFactory::unauthorized(ErrorCodes::AUTH_TOKEN_EXPIRED, 'Token has expired.');
return ResponseFactory::forbidden(ErrorCodes::AUTH_USER_FORBIDDEN, 'You do not have permission.');
return ResponseFactory::conflict(ErrorCodes::USER_EMAIL_DUPLICATE, 'Email already registered.');

Bulk partial failure (207)

return ResponseFactory::bulkPartialFailure([
    'created' => 1,
    'failed'  => 1,
    'items'   => [
        ['index' => 0, 'success' => true,  'id' => '550e8400-...'],
        ['index' => 1, 'success' => false, 'code' => 'USER_EMAIL_DUPLICATE', 'message' => 'Email already registered.'],
    ],
]);

Rate limited (429) / Server error (500)

return ResponseFactory::rateLimited();
return ResponseFactory::serverError('Something went wrong.');

Error Codes

All standard error codes are available as constants:

use Vandet\ApiResponse\Constants\ErrorCodes;

ErrorCodes::AUTH_TOKEN_EXPIRED
ErrorCodes::USER_NOT_FOUND
ErrorCodes::VALIDATION_FAILED
ErrorCodes::RESOURCE_NOT_FOUND
ErrorCodes::SERVER_UNEXPECTED_ERROR
// ... and 35 more

See src/Constants/ErrorCodes.php for the full list, or refer to 04-error-code-standard.md.

Exception Handler

The package automatically intercepts Laravel exceptions on JSON requests and converts them to the standard envelope.

Exception	HTTP	Code
`ValidationException`	422	`VALIDATION_FAILED`
`AuthenticationException`	401	`AUTH_TOKEN_MISSING`
`AuthorizationException`	403	`AUTH_USER_FORBIDDEN`
`ModelNotFoundException`	404	`RESOURCE_NOT_FOUND`
`NotFoundHttpException`	404	`RESOURCE_NOT_FOUND`
`TooManyRequestsHttpException`	429	`SERVER_RATE_LIMITED`
`Throwable` (catch-all)	500	`SERVER_UNEXPECTED_ERROR`

Only requests with Accept: application/json are intercepted — web/HTML routes are unaffected.

Disabling the exception handler

To disable all automatic exception handling:

// config/api-response.php
'handle_exceptions' => false,

To disable specific exception types:

'exceptions' => [
    'validation'     => true,
    'authentication' => true,
    'authorization'  => false, // handle manually
    'not_found'      => true,
    'rate_limited'   => true,
    'server_error'   => true,
],

Conflict with an existing exception handler

If your service already has custom exception handling, the package renderables take priority for matched types. To opt out of specific types (see above) and handle them yourself, use $exceptions['type'] => false in the config.

Using ResponseFactory in a Custom Exception Handler

You can use ResponseFactory directly inside your own exception handler alongside or instead of the package's built-in renderables.

Laravel 11 — `bootstrap/app.php`

use Illuminate\Foundation\Configuration\Exceptions;
use Vandet\ApiResponse\Http\ResponseFactory;
use Vandet\ApiResponse\Constants\ErrorCodes;
use App\Exceptions\PaymentFailedException;
use App\Exceptions\TenantSuspendedException;

->withExceptions(function (Exceptions $exceptions) {

    // Custom domain exception
    $exceptions->renderable(function (PaymentFailedException $e, $request) {
        if ($request->expectsJson()) {
            return ResponseFactory::conflict(
                ErrorCodes::PAYMENT_FAILED,
                $e->getMessage()
            );
        }
    });

    // Another domain exception
    $exceptions->renderable(function (TenantSuspendedException $e, $request) {
        if ($request->expectsJson()) {
            return ResponseFactory::forbidden(
                ErrorCodes::TENANT_SUSPENDED,
                'This account has been suspended.'
            );
        }
    });

})

Laravel 10 — `app/Exceptions/Handler.php`

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Http\Request;
use Vandet\ApiResponse\Http\ResponseFactory;
use Vandet\ApiResponse\Constants\ErrorCodes;
use App\Exceptions\PaymentFailedException;
use App\Exceptions\TenantSuspendedException;

class Handler extends ExceptionHandler
{
    public function register(): void
    {
        $this->renderable(function (PaymentFailedException $e, Request $request) {
            if ($request->expectsJson()) {
                return ResponseFactory::conflict(
                    ErrorCodes::PAYMENT_FAILED,
                    $e->getMessage()
                );
            }
        });

        $this->renderable(function (TenantSuspendedException $e, Request $request) {
            if ($request->expectsJson()) {
                return ResponseFactory::forbidden(
                    ErrorCodes::TENANT_SUSPENDED,
                    'This account has been suspended.'
                );
            }
        });
    }
}

Custom domain exception pattern

Define your exception with a built-in error code so the handler stays clean:

class PaymentFailedException extends \RuntimeException
{
    public function __construct(string $message = 'Payment gateway rejected the transaction.')
    {
        parent::__construct($message);
    }
}

Then throw it anywhere in your application:

throw new PaymentFailedException('Card declined.');

The handler catches it and returns:

{ "success": false, "message": "Card declined.", "code": "PAYMENT_FAILED", "errors": {} }

ApiException — built-in base class

The package ships with ApiException, a base class your domain exceptions can extend. It stores the error code and HTTP status directly on the exception — no renderable registration needed.

use Vandet\ApiResponse\Exceptions\ApiException;
use Vandet\ApiResponse\Constants\ErrorCodes;

class PaymentFailedException extends ApiException
{
    public function __construct(string $message = 'Payment gateway rejected the transaction.')
    {
        parent::__construct(ErrorCodes::PAYMENT_FAILED, $message, 422);
    }
}

class TenantSuspendedException extends ApiException
{
    public function __construct()
    {
        parent::__construct(ErrorCodes::TENANT_SUSPENDED, 'This account has been suspended.', 403);
    }
}

Throw from anywhere — controller, action, service — and the package handler responds automatically:

// In an Action or Service
if ($tenant->isSuspended()) {
    throw new TenantSuspendedException();
}

// In a controller
throw new PaymentFailedException('Card declined.');

{ "success": false, "message": "Card declined.", "code": "PAYMENT_FAILED", "errors": {} }

No need to register a renderable() for each exception type. All classes that extend ApiException are caught by the service provider automatically.

Generic one-off errors without a custom class

Use ResponseFactory::error() when you need a specific code and status without creating a dedicated exception class:

use Vandet\ApiResponse\Http\ResponseFactory;
use Vandet\ApiResponse\Constants\ErrorCodes;

return ResponseFactory::error(ErrorCodes::ORDER_CANCELLED, 'Order has been cancelled.', 409);

Tip — disable the built-in handler for types you own

If your service handles its own ModelNotFoundException with a domain-specific message, disable the package's version in config/api-response.php to avoid conflicts:

'exceptions' => [
    'not_found' => false, // I handle this myself
],

Response Envelope Reference

// Success
{ "success": true,  "message": "...", "data": {} }
{ "success": true,  "message": "...", "data": [], "pagination": {}, "links": {} }
{ "success": true,  "message": "...", "data": [], "included": {} }

// Error
{ "success": false, "message": "...", "code": "DOMAIN_ENTITY_REASON", "errors": {} }

// Delete
HTTP 204 No Content

// Bulk partial (only error response that includes data)
{ "success": false, "message": "...", "code": "BULK_PARTIAL_FAILURE", "data": { "items": [] }, "errors": {} }

Optional fields (pagination, links, included, meta) are omitted entirely when absent — never null.

Running Tests

composer install
./vendor/bin/phpunit

Changelog

Version	Date	Change
1.0.0	2026-06-26	Initial release

vandet / laravel-api-response

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Option 1 — Composer (recommended)

Option 2 — Clone the repository

Publish the config (optional)

Usage

ResponseFactory

Success — single resource

Success — created (201)

Success — accepted async job (202)

Success — paginated collection

Success — with reference data

Delete (204 — no body)

Validation error (422)

Not found (404)

Unauthorized (401) / Forbidden (403) / Conflict (409)

Bulk partial failure (207)

Rate limited (429) / Server error (500)

Error Codes

Exception Handler

Disabling the exception handler

Conflict with an existing exception handler

Using ResponseFactory in a Custom Exception Handler

Laravel 11 — `bootstrap/app.php`

Laravel 10 — `app/Exceptions/Handler.php`

Custom domain exception pattern

ApiException — built-in base class

Generic one-off errors without a custom class

Tip — disable the built-in handler for types you own

Response Envelope Reference

Running Tests

Changelog

vandet / laravel-api-response

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Option 1 — Composer (recommended)

Option 2 — Clone the repository

Publish the config (optional)

Usage

ResponseFactory

Success — single resource

Success — created (201)

Success — accepted async job (202)

Success — paginated collection

Success — with reference data

Delete (204 — no body)

Validation error (422)

Not found (404)

Unauthorized (401) / Forbidden (403) / Conflict (409)

Bulk partial failure (207)

Rate limited (429) / Server error (500)

Error Codes

Exception Handler

Disabling the exception handler

Conflict with an existing exception handler

Using ResponseFactory in a Custom Exception Handler

Laravel 11 — bootstrap/app.php

Laravel 10 — app/Exceptions/Handler.php

Custom domain exception pattern

ApiException — built-in base class

Generic one-off errors without a custom class

Tip — disable the built-in handler for types you own

Response Envelope Reference

Running Tests

Changelog

Laravel 11 — `bootstrap/app.php`

Laravel 10 — `app/Exceptions/Handler.php`