PHPackages                             anyo-lab/api-response - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. anyo-lab/api-response

ActiveLibrary[HTTP & Networking](/categories/http)

anyo-lab/api-response
=====================

A Laravel package for universal API response and error handling

v2.0.0(4mo ago)07↓93.3%MITPHPPHP ^8.1CI passing

Since Aug 11Pushed 4mo agoCompare

[ Source](https://github.com/anyo-lab/api-response)[ Packagist](https://packagist.org/packages/anyo-lab/api-response)[ Docs](https://github.com/laravel-api-response/api-response)[ RSS](/packages/anyo-lab-api-response/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (8)Versions (4)Used By (0)

Laravel API Response
====================

[](#laravel-api-response)

[![Latest Version on Packagist](https://camo.githubusercontent.com/59158b7ffb15b1b86029fd870ed663a223e61d8ffc584d0e13c11bbfecf86585/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616e796f2d6c61622f6170692d726573706f6e73652e737667)](https://packagist.org/packages/anyo-lab/api-response)[![Total Downloads](https://camo.githubusercontent.com/acb768313241cd9f183b03514fd51110d67f1491f8c29496dec660afe3833570/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616e796f2d6c61622f6170692d726573706f6e73652e737667)](https://packagist.org/packages/anyo-lab/api-response)[![License](https://camo.githubusercontent.com/dd5f4a1fddbe19c72b5bd80442450d2c245333a521568485b2d046fa826440b2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616e796f2d6c61622f6170692d726573706f6e73652e737667)](https://github.com/anyo-lab/api-response/blob/main/LICENSE)[![Tests](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e)](https://github.com/anyo-lab/api-response)

A comprehensive Laravel package for universal API response and error handling. This package provides a standardized way to format API responses and handle exceptions in Laravel applications with multiple usage patterns and advanced features.

🚀 Features
----------

[](#-features)

- **🎯 Standardized API Responses** - Consistent response format across your entire API
- **🛡️ Automatic Exception Handling** - Custom exception handler for API routes
- **📝 Multiple Usage Methods** - Use as service, trait, facade, macros, or helper functions
- **⚙️ Highly Configurable** - Customize response structure and messages
- **📊 Built-in Pagination** - Automatic pagination response formatting
- **🔧 Laravel 9-12 Support** - Compatible with multiple Laravel versions
- **🎯 Resource Classes** - Built-in resource transformation classes
- **🔌 Response Macros** - Extend Laravel's response with API methods
- **🌐 Global Helpers** - Easy-to-use global helper functions
- **🛠️ Middleware Support** - Automatic response formatting middleware
- **🚦 Rate Limiting Integration** - Formatted rate limiting responses
- **📦 Response Compression** - Automatic response compression (gzip, deflate)
- **🔄 API Versioning** - Built-in API versioning support
- **📈 Performance Monitoring** - Response performance tracking

📋 Requirements
--------------

[](#-requirements)

- PHP >= 8.1
- Laravel >= 9.0

🔧 Installation
--------------

[](#-installation)

### Via Composer

[](#via-composer)

```
composer require anyo-lab/api-response
```

### Manual Installation

[](#manual-installation)

1. Clone or download this package
2. Add to your `composer.json`:

```
{
    "require": {
        "anyo-lab/api-response": "*"
    },
    "repositories": [
        {
            "type": "path",
            "url": "path/to/api-response"
        }
    ]
}
```

3. Run `composer update`

⚙️ Configuration
----------------

[](#️-configuration)

Publish the configuration file:

```
php artisan vendor:publish --provider="ApiResponse\ApiResponseServiceProvider" --tag="api-response-config"
```

This will create `config/api-response.php` with customizable options.

Production readiness
--------------------

[](#production-readiness)

Before using in a live project:

1. **Set `APP_DEBUG=false`** in `.env` so error responses never expose stack traces or file paths.
2. **Publish config** (optional): `php artisan vendor:publish --tag=api-response-config` to override messages, structure, or timestamp format.
3. **Override messages** in `config/api-response.php` under `messages` so all default strings (e.g. "Resource not found") come from one place.
4. **Optional:** Enable `include_request_id` and `include_error_codes` in config for tracing and machine-readable error codes.

All responses use the same config (structure, timestamp, error codes). `ResponseHelper` and resources use the same settings as the main `ApiResponse` service.

Upgrading / Breaking changes
----------------------------

[](#upgrading--breaking-changes)

- **Response caching removed:** The package no longer provides `api_cache()`, `api_remember()`, or `ApiResponseCache`. For cached API responses, use Laravel’s `Cache::remember()` with `api_success()`:

    ```
    use Illuminate\Support\Facades\Cache;

    $data = Cache::remember('users.list', 3600, fn () => User::all());
    return api_success($data, 'Success');
    ```
- **204 No Content:** `noContent()` now returns an empty response body (RFC 7231) instead of a JSON body.
- **Performance monitoring optional:** Set `register_performance_monitoring` to `false` in config to disable cache usage when you do not use `api_performance()`.

See [CHANGELOG.md](CHANGELOG.md) for full version history.

🎯 Quick Start
-------------

[](#-quick-start)

### Basic Usage

[](#basic-usage)

```
use ApiResponse\ApiResponse;

class UserController extends Controller
{
    public function index(ApiResponse $apiResponse)
    {
        $users = User::paginate(10);

        return $apiResponse->paginated($users, 'Users retrieved successfully');
    }

    public function store(Request $request, ApiResponse $apiResponse)
    {
        $user = User::create($request->validated());

        return $apiResponse->created($user, 'User created successfully');
    }
}
```

**Tip:** For testability and flexibility, type-hint `ApiResponseContract` instead of `ApiResponse` so you can swap or mock the implementation.

📖 Usage Methods
---------------

[](#-usage-methods)

### Method 1: Service Injection

[](#method-1-service-injection)

```
use ApiResponse\ApiResponse;

class UserController extends Controller
{
    public function index(ApiResponse $apiResponse)
    {
        $users = User::paginate(10);

        return $apiResponse->paginated($users, 'Users retrieved successfully');
    }

    public function store(Request $request, ApiResponse $apiResponse)
    {
        $user = User::create($request->validated());

        return $apiResponse->created($user, 'User created successfully');
    }
}
```

### Method 2: Trait Usage

[](#method-2-trait-usage)

```
use ApiResponse\Traits\ApiResponseTrait;

class UserController extends Controller
{
    use ApiResponseTrait;

    public function index()
    {
        $users = User::paginate(10);

        return $this->paginatedResponse($users, 'Users retrieved successfully');
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());

        return $this->createdResponse($user, 'User created successfully');
    }
}
```

### Method 3: Facade Usage

[](#method-3-facade-usage)

```
use ApiResponse\Facades\ApiResponse;

class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate(10);

        return ApiResponse::paginated($users, 'Users retrieved successfully');
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());

        return ApiResponse::created($user, 'User created successfully');
    }
}
```

### Method 4: Response Macros

[](#method-4-response-macros)

```
class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate(10);

        return response()->apiPaginated($users, 'Users retrieved successfully');
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());

        return response()->apiCreated($user, 'User created successfully');
    }
}
```

### Method 5: Global Helper Functions

[](#method-5-global-helper-functions)

```
class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate(10);

        return api_paginated($users, 'Users retrieved successfully');
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());

        return api_created($user, 'User created successfully');
    }
}
```

### Method 6: Resource Classes

[](#method-6-resource-classes)

```
use ApiResponse\Resources\ApiResource;
use Illuminate\Http\Request;

class UserResource extends ApiResource
{
    protected function transformData(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'created_at' => $this->created_at?->toISOString(),
        ];
    }

    protected function getMessage(): string
    {
        return 'User retrieved successfully';
    }
}

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::findOrFail($id);

        return new UserResource($user);
    }

    public function index()
    {
        $users = User::paginate(10);

        return UserResource::collection($users);
    }
}
```

📤 Response Methods
------------------

[](#-response-methods)

### Success Responses

[](#success-responses)

```
// Basic success response
$apiResponse->success($data, 'Success message');

// Created response (201)
$apiResponse->created($data, 'Resource created');

// No content response (204)
$apiResponse->noContent('No content available');

// Paginated response
$apiResponse->paginated($paginator, 'Data retrieved');

// Collection response
$apiResponse->collection($collection, 'Data retrieved');

// Resource response
$apiResponse->resource($resource, 'Resource retrieved');
```

### Error Responses

[](#error-responses)

```
// Basic error response
$apiResponse->error('Error message', 400);

// Validation error (422)
$apiResponse->validationError($errors, 'Validation failed');

// Not found (404)
$apiResponse->notFound('Resource not found');

// Unauthorized (401)
$apiResponse->unauthorized('Authentication required');

// Forbidden (403)
$apiResponse->forbidden('Access denied');

// Server error (500)
$apiResponse->serverError('Internal server error');

// Bad request (400)
$apiResponse->badRequest('Invalid request');

// Conflict (409)
$apiResponse->conflict('Resource conflict');

// Too many requests (429)
$apiResponse->tooManyRequests('Rate limit exceeded');
```

📋 Response Format
-----------------

[](#-response-format)

All responses follow this standardized format:

### Success Response

[](#success-response)

```
{
    "success": true,
    "message": "Success message",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "errors": null,
    "meta": null,
    "timestamp": "2024-01-01T12:00:00.000000Z"
}
```

### Error Response

[](#error-response)

```
{
    "success": false,
    "message": "Error message",
    "data": null,
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password must be at least 8 characters."]
    },
    "meta": null,
    "timestamp": "2024-01-01T12:00:00.000000Z"
}
```

### Pagination Response

[](#pagination-response)

```
{
    "success": true,
    "message": "Data retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "John Doe"
        }
    ],
    "errors": null,
    "meta": {
        "current_page": 1,
        "per_page": 10,
        "total": 100,
        "last_page": 10,
        "from": 1,
        "to": 10,
        "has_more_pages": true
    },
    "timestamp": "2024-01-01T12:00:00.000000Z"
}
```

🛡️ Exception Handling
---------------------

[](#️-exception-handling)

The package includes a custom exception handler that automatically formats exceptions for API routes:

ExceptionStatus CodeDescription`ValidationException`422Validation errors`AuthenticationException`401Unauthorized`ModelNotFoundException`404Not found`NotFoundHttpException`404Not found`QueryException`500Server error (with debug info in development)`HttpException`RespectiveHTTP status code⚙️ Configuration Options
------------------------

[](#️-configuration-options)

### Response Structure

[](#response-structure)

```
'structure' => [
    'success' => 'success',
    'message' => 'message',
    'data' => 'data',
    'errors' => 'errors',
    'meta' => 'meta',
    'timestamp' => 'timestamp',
],
```

### Default Messages

[](#default-messages)

```
'messages' => [
    'success' => 'Success',
    'created' => 'Resource created successfully',
    'updated' => 'Resource updated successfully',
    'deleted' => 'Resource deleted successfully',
    'not_found' => 'Resource not found',
    'unauthorized' => 'Unauthorized',
    'forbidden' => 'Forbidden',
    'validation_failed' => 'Validation failed',
    'server_error' => 'Internal server error',
    'bad_request' => 'Bad request',
    'conflict' => 'Conflict occurred',
    'too_many_requests' => 'Too many requests',
],
```

### Other Options

[](#other-options)

```
'include_timestamp' => true,
'timestamp_format' => 'Y-m-d H:i:s',
'debug' => env('APP_DEBUG', false),
'use_exception_handler' => true,
'api_routes_pattern' => 'api/*',
```

🔄 Advanced Features
-------------------

[](#-advanced-features)

### Middleware Support

[](#middleware-support)

```
// In your routes/api.php
Route::middleware(['api.response'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    Route::post('/users', [UserController::class, 'store']);
});

// Or register globally in App\Http\Kernel.php
protected $middlewareGroups = [
    'api' => [
        \ApiResponse\Http\Middleware\ApiResponseMiddleware::class,
        // ... other middleware
    ],
];
```

### API Versioning

[](#api-versioning)

```
use ApiResponse\Services\ApiVersioningService;

class UserController extends Controller
{
    public function index(ApiVersioningService $versioning)
    {
        $version = $versioning->getVersion(request());

        if ($version === 'v2') {
            // Return v2 format
            return $this->paginatedResponseV2($users);
        }

        // Return v1 format
        return $this->paginatedResponse($users);
    }
}
```

### Response Compression

[](#response-compression)

```
use ApiResponse\Services\ResponseCompressionService;

class UserController extends Controller
{
    public function index(ResponseCompressionService $compression)
    {
        $response = $this->paginatedResponse($users);

        return $compression->compress(request(), $response);
    }
}
```

### Performance Monitoring

[](#performance-monitoring)

```
use ApiResponse\Services\PerformanceMonitoringService;

class UserController extends Controller
{
    public function index(PerformanceMonitoringService $monitoring)
    {
        $monitoring->startMonitoring(request());

        $users = User::paginate(10);
        $response = $this->paginatedResponse($users);

        $monitoring->endMonitoring(request(), $response);

        return $response;
    }
}
```

🧪 Testing
---------

[](#-testing)

```