README

Laravel API Response is a powerful and flexible package that provides a standardized way to structure API responses in Laravel applications. It offers a range of features to enhance your API development experience, including consistent response formatting, conditional responses, pagination support, rate limiting, and more.

1. [Installation](#installation)
2. [Configuration](#configuration)
3. [Basic Usage](#basic-usage)
4. [Feature](#feature)
    - [Success Response](#success-response)
    - [Error Response](#error-response)
    - [Conditional Response](#conditional-response)
    - [Pagination](#pagination)
    - [Rate Limiting](#rate-limiting)
    - [Response Compression](#response-compression)
    - [Localization](#localization)
    - [HATEOAS Links](#hateoas-links)
    - [Logging](#logging)
5. [Advanced Usage](#advanced-usage)
6. [Testing](#testing)
7. [Changelog](#changelog)
8. [Contributing](#contributing)
9. [Security Vulnerabilities](#security-vulnerabilities)
10. [Credits](#credits)
11. [License](#license)

1. Installation

You can install the package via composer:

composer require creativecrafts/laravel-api-response

2. Configuration

The package comes with a default configuration file that you can publish to your application using the following command:

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

This will create a laravel-api-response.php file in your config directory. You can customize various aspects of the package behavior in this file.

3. Basic Usage

There are two ways to use the Laravel API Response in your controllers:

Using Dependency Injection

You can inject the LaravelApi class:

use CreativeCrafts\LaravelApiResponse\LaravelApi;

class UserController extends Controller
{
    protected $api;

    public function __construct(LaravelApi $api)
    {
        $this->api = $api;
    }

    public function index()
    {
        $users = User::all();
        return $this->api->successResponse('Users retrieved successfully', $users);
    }
}

Using the Facade

For a more Laravel-like experience, you can use the LaravelApiResponse facade:

use CreativeCrafts\LaravelApiResponse\Facades\LaravelApiResponse;

class UserController extends Controller
{
    public function index()
    {
        $users = User::all();
        return LaravelApiResponse::successResponse('Users retrieved successfully', $users);
    }
}

4. Feature

The Laravel API Response package provides a range of features to help you build robust and reliable APIs. Here are some of the key features:

Success Responses

To return a success response:

return $this->api->successResponse('Operation successful', $data);

Error Responses

To return an error response:

return $this->api->errorResponse('An error occurred', $errorCode, $statusCode);

Conditional Responses

For responses that support caching and conditional requests:

return $this->api->conditionalResponse($data, 'Data retrieved successfully');

This method automatically handles ETag and Last-Modified headers for efficient caching.

Pagination

The package supports Laravel's pagination:

$users = User::paginate(15);
return $this->api->paginatedResponse('Users retrieved successfully', $users);

Rate Limiting

Rate limiting is automatically applied to API routes. You can configure the rate limit in the laravel-api-response.php config file:

'rate_limit_max_attempts' => env('API_RATE_LIMIT_MAX_ATTEMPTS', 60),
'rate_limit_decay_minutes' => env('API_RATE_LIMIT_DECAY_MINUTES', 1),

Response Compression

Response compression can be enabled or disabled in the config:

'enable_compression' => env('API_RESPONSE_COMPRESSION', true),

Localization

The package supports message localization. Use the localize method to translate messages:

$message = $this->api->localize('messages.welcome');

HATEOAS Links

You can include HATEOAS links in your responses:

$links = [
    'self' => ['href' => '/api/users/1'],
    'posts' => ['href' => '/api/users/1/posts'],
];

return $this->api->successResponse('User retrieved', $userData, 200, [], $links);

Logging

API responses are logged to a dedicated channel. You can configure the channel in the config file:

'log_channel' => 'api',

Exception Handling

The package includes a custom exception handler that automatically formats exceptions into consistent API responses. This is enabled by default and can be configured in the config file:

'use_exception_handler' => env('API_USE_EXCEPTION_HANDLER', true),

When enabled, the exception handler will automatically catch exceptions and format them into API responses with appropriate status codes. For example:

Validation exceptions will be formatted as validation error responses
Model not found exceptions will be formatted as 404 error responses
Authentication exceptions will be formatted as 401 error responses
Authorization exceptions will be formatted as 403 error responses

This ensures consistent error responses across your API without requiring extra code in your controllers.

5. Advanced Usage

The Laravel API Response package provides a range of advanced features to help you build robust and reliable APIs. Here are some of the key features:

Custom Response Structure

You can customize the response structure in the config file:

'response_structure' => [
    'success_key' => 'success',
    'message_key' => 'message',
    'data_key' => 'data',
    'errors_key' => 'errors',
    'error_code_key' => 'error_code',
    'meta_key' => 'meta',
    'links_key' => '_links',
    'include_api_version' => true,
],

Filtering Response Fields

You can filter the fields returned in the response:

$fields = ['id', 'name', 'email'];
return $this->api->successResponse('User data', $userData, 200, [], [], $fields);

Custom Status Codes

You can specify custom HTTP status codes for your responses:

return $this->api->successResponse('Resource created', $newResource, 201);

Extending with Custom Methods

The LaravelApi class uses Laravel's Macroable trait, allowing you to add custom response methods at runtime:

use CreativeCrafts\LaravelApiResponse\LaravelApi;
use Illuminate\Support\Facades\Response;

LaravelApi::macro('teapotResponse', function ($message = "I'm a teapot") {
    return Response::json(['message' => $message], 418);
});

// Then in your controller:
return $this->api->teapotResponse();
// Or using the facade:
return LaravelApiResponse::teapotResponse("Custom teapot message");

This makes it easy to extend the package with your own custom response types without modifying the core code.

Version 2: Breaking Changes

Version 2 of the package introduces one breaking change.

createdResponse method has been removed. Use successResponse instead.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

creativecrafts / laravel-api-response

Maintainers

Details