README

Laravel API Response Formatter

A powerful Laravel package that standardizes your API responses with a clean, expressive syntax. Perfect for building consistent RESTful APIs.

Features

🚀 Simple & Expressive API - Fluent interface for building responses
🎯 Consistent Format - Standardized response structure across your API
📦 Built-in Support for:
- Success/Error responses
- Validation errors
- Pagination
- Custom headers
- Exception handling
⚙️ Highly Configurable - Customize keys, messages, and more
🔒 Type-Safe - Full TypeScript-like safety with PHP 7.4+
🧪 Well Tested - Comprehensive test coverage

Quick Start

Installation

composer require darshphpdev/laravel-api-response-formatter

Basic Usage

// Success Response
return api_response()
    ->success()
    ->message('Welcome!')
    ->send(['name' => 'Laravel']);

// Error Response
return api_response()
    ->error()
    ->code(404)
    ->message('Resource Not Found')
    ->send();

// With Validation Errors
return api_response()
    ->error()
    ->code(422)
    ->message('Validation Error')
    ->validationErrors($errors)
    ->send();

// With Pagination
return api_response()
    ->success()
    ->send(User::paginate(10));

Response Format

{
    "status": {
        "code": 200,
        "message": "Welcome!",
        "error": false,
        "validation_errors": []
    },
    "data": {
        "name": "Laravel"
    }
}

Documentation

Configuration

Publish the config file:

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

Customize response keys, messages, and more in config/api-response.php:

return [
    'keys' => [
        'status' => 'status',
        'code' => 'code',
        // ... customize your keys
    ],
    'logging' => [
        'enabled' => env('API_RESPONSE_LOGGING', false),
    ],
    'error_messages' => [
        200 => 'Success',
        404 => 'Resource Not Found',
        // ... customize your messages
    ],
];

Exception Handling

Add the trait to your controllers:

use DarshPhpDev\LaravelApiResponseFormatter\Traits\HandlesApiExceptions;

class UserController extends Controller
{
    use HandlesApiExceptions;

    public function show($id)
    {
        try {
            $user = User::findOrFail($id);
            return api_response()
                ->success()
                ->send($user);
        } catch (\Throwable $e) {
            return $this->handleApiException($e);
        }
    }
}

Advanced Usage

Method Chaining

return api_response()
    ->success()
    ->message('Created successfully')
    ->code(201)
    ->headers(['X-Custom-Header' => 'Value'])
    ->send($data);

Pagination Support

$users = User::paginate(10);

return api_response()
    ->success()
    ->message('Users retrieved')
    ->send($users);

Response includes pagination metadata:

{
    "status": { ... },
    "data": {
        "items": [...],
        "pagination": {
            "total": 100,
            "per_page": 10,
            "current_page": 1,
            "last_page": 10
        }
    }
}

Testing

composer test

Compatibility

PHP 7.4+
Laravel 5.x and above
PHPUnit 9.x for testing

Contributing

Contributions are welcome!

Security

If you discover any security-related issues, please email [mustafa.softcode@gmail.com] instead of using the issue tracker.

Credits

License

This package is open-source software licensed under the MIT License.

darshphpdev / laravel-api-response-formatter

Maintainers

Details