README

A Laravel package that provides a fluent and expressive interface for creating standardized JSON API responses.

Installation

You can install the package via composer:

composer require osama-98/laravel-response-api

Requirements

PHP ^8.0
Laravel ^8.0

Response Structure

All responses follow this standardized JSON structure:

{
    "message": "Human-readable message",
    "body": {
        // Response data (optional) 
    },
    "errors": {
        // Validation or error details (optional) 
    }
}

Basic Usage

Success Response

return ApiResponse::success(
    data: ['user' => $user],
    message: 'User retrieved successfully'
);

Response:

{
    "message": "User retrieved successfully",
    "body": {
        "user": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        }
    }
}

Error Response

return ApiResponse::error(
    message: 'Validation failed.',
    errors: $validator->errors()->toArray()
);

Response:

{
    "message": "Validation failed.",
    "errors": {
        "email": [
            "The email field must be a valid email address.",
            "The selected email is invalid."
        ]
    }
}

Pagination Support

Using with Resource

return ApiResponse::pagination(
    paginator: User::paginate(10),
    mapper: UserResource::class
);

Using with Custom Mapper

return ApiResponse::pagination(paginator: User::paginate(10), mapper: fn(User $user) => [
    'id' => $user->id,
    'name' => $user->name
]);

Fluent Builder

For more complex responses, use the fluent builder:

return ApiResponse::builder()
    ->data(['key' => 'value'])
    ->message('Custom message')
    ->errors(['field' => 'error message'])
    ->status(Response::HTTP_BAD_REQUEST)
    ->send();

Testing

composer test

This runs:

Code style checks (Laravel Pint)
Static analysis (PHPStan)
Unit tests (Pest PHP)
Type coverage tests

Security

If you discover any security-related issues, please email osama.sada98@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

osama-98 / laravel-response-api

Maintainers

Details