sevaske/laravel-api-response

The package for building clean, consistent, and predictable JSON API responses in laravel applications.

2.0.1 2026-07-15 20:31 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• sevaske/api-response-payload: ^1.0

Requires (Dev)

• larastan/larastan: ^3.10
• laravel/pint: ^1.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

• sevaske

• json
• api
• http response
• response
• laravel
• api response
• laravel api

Published on Packagist.org on 2026-07-15 20:34 UTC

README

A simple library for a simple task: building consistent JSON API responses in Laravel. Fully customizable when you need it

Features

• Unified success/error JSON responses
• Response macros
• Global helper
• Configurable response structure
• Custom payload builders
• Laravel paginator support
• Dependency injection friendly

Default response format

Out of the box, the response looks like this:

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1
  }
}

Error response:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": "Invalid"
  }
}

Response structure is fully configurable through the config file or by replacing the payload builder.

Requirements

• PHP ^8.3
• Laravel ^11.0|^12.0|^13.0

Installation

composer require sevaske/laravel-api-response

Configuration

Publish the config:

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

Usage

1. Dependency Injection (recommended)

use Sevaske\LaravelApiResponse\Contracts\ApiResponseContract;

class UserController
{
    public function __construct(
        private ApiResponseContract $api
    ) {}

    public function show(User $user)
    {
        return $this->api->success(
            data: $user
        );
    }
}

2. Via response() macros

return response()->success(
    message: 'OK',
    data: ['id' => 1],
);

return response()->error(
    message: 'Validation failed',
    errors: ['email' => 'Invalid']
);

3. Via helper

return api()->success(
    message: 'OK',
    data: ['id' => 1],
);

Pagination

Pagination follows Laravel's native JSON resource behavior.

If a JsonResource or ResourceCollection wrapping a paginator is passed as data, all pagination fields generated by Laravel are preserved automatically.

There is no custom pagination format and no additional abstraction layer — the library simply remaps the data key while keeping the rest of the response intact.

Supported paginators:

• LengthAwarePaginator (paginate())
• Paginator (simplePaginate())
• CursorPaginator (cursorPaginate())

use App\Http\Resources\UserResource;
use App\Models\User;

$users = User::paginate();

return api()->success(
    data: UserResource::collection($users)
);

Customization

Change response keys:

return [
    'success_key' => 'ok',
    'message_key' => 'msg',
    'data_key'    => 'results',
    'errors_key'  => 'errors',
];

Change the "success" value format:

return [
    'success_value' => 1,
    'error_value'   => 0,
];

Extending

Bind your own response implementation and payload builder

// App\Providers\AppServiceProvider.php

use Sevaske\LaravelApiResponse\Contracts\ApiResponseContract;

public function register(): void
{
    $this->app->bind(
        ApiResponseContract::class,
        MyCustomApiResponse::class
    );
    
    $this->app->bind(
        ApiResponsePayloadContract::class, 
        MyPayloadBuilder::class
    );
}

This allows full control over the final response structure without touching controllers.

License

MIT