README

A simple, consistent JSON API response standard for Laravel applications.

This package helps you return clean, predictable JSON responses for success and error cases without repeating boilerplate code.

Features

Unified success responses
Unified error responses and fail() alias
Pagination helper (standard format with meta)
Validation error formatting
Exception handler integration helper
Optional controller trait
Response macros (response()->apiSuccess(), etc.)
Configurable response keys and default messages
Lightweight and framework-friendly

Requirements

PHP 8.1 or higher
Laravel 9, 10, or 11

Installation

Install the package via Composer:

composer require ifar/laravel-api-responses

Publish the configuration file (optional):

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

Default Response Format

Success response

{
  "success": true,
  "message": "Operation successful",
  "data": {},
  "meta": null
}

Error response

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."]
  }
}

Usage

Using the ApiResponse class

use Ifar\ApiResponses\ApiResponse;

return ApiResponse::success($data, 'User created');

return ApiResponse::error('Unauthorized', 401);
return ApiResponse::fail('Not found', 404);  // alias for error()

Pagination

Return paginated data with pagination meta in the standard format:

use Ifar\ApiResponses\ApiResponse;

$users = User::paginate(15);
return ApiResponse::paginated($users, 'Users retrieved');

Response includes data (items) and meta (current_page, last_page, per_page, total, from, to).

Validation errors

Format Laravel's ValidationException into your standard error response (e.g. in your exception handler or when catching validation failures):

use Ifar\ApiResponses\ApiResponse;
use Illuminate\Validation\ValidationException;

// In exception handler or when catching ValidationException:
return ApiResponse::validationFailed($e);

Response (status 422):

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name field must be at least 2 characters."]
  }
}

Exception handler integration

Use fromException() in your exception handler to return this package’s format for ValidationException (and fall back to your default for others):

use Ifar\ApiResponses\ApiResponse;

// In App\Exceptions\Handler (or bootstrap/app.php exception handler)
public function register(): void
{
    $this->renderable(function (Throwable $e, Request $request) {
        if ($request->expectsJson() && $response = ApiResponse::fromException($e)) {
            return $response;
        }
    });
}

Response macros

You can use the response() helper with macros instead of the ApiResponse class:

return response()->apiSuccess($data, 'Created');
return response()->apiError('Not found', 404);
return response()->apiFail('Forbidden', 403);       // alias
return response()->apiValidationFailed($e);
return response()->apiPaginated($paginator, 'List');

Using the ApiResponds trait (recommended)

use Ifar\ApiResponses\Traits\ApiResponds;
use Illuminate\Validation\ValidationException;

class UserController extends Controller
{
    use ApiResponds;

    public function store()
    {
        return $this->success($user, 'User created');
    }

    public function index()
    {
        return $this->paginated(User::paginate(15), 'Users list');
    }

    public function update(Request $request, User $user)
    {
        try {
            $validated = $request->validate([...]);
        } catch (ValidationException $e) {
            return $this->validationFailed($e);
        }
        // ...
    }
}

Trait methods: success(), error(), fail(), paginated(), validationFailed().

Configuration

You may customize the response structure and default messages. Config uses plural groups for future expansion:

return [
    'keys' => [
        'success_key' => 'success',
        'message_key' => 'message',
        'data_key'    => 'data',
        'errors_key'  => 'errors',
        'meta_key'    => 'meta',
    ],

    'defaults' => [
        'success_message' => '',
        'error_message'   => 'An error occurred.',
    ],
];

When you pass an empty string for message to success() or error(), the corresponding default from defaults is used.

Testing

composer install
./vendor/bin/phpunit

When to use this package

Building REST APIs
Maintaining consistent response formats
Reducing repeated response boilerplate
Team-based or long-term projects

License

MIT

ifar / laravel-api-responses

Maintainers

Details