Laravel 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

🎯 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

PHP >= 8.1
Laravel >= 9.0

🔧 Installation

Via Composer

composer require anyo-lab/api-response

Manual Installation

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

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

Run composer update

⚙️ 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

Before using in a live project:

Set APP_DEBUG=false in .env so error responses never expose stack traces or file paths.
Publish config (optional): php artisan vendor:publish --tag=api-response-config to override messages, structure, or timestamp format.
Override messages in config/api-response.php under messages so all default strings (e.g. "Resource not found") come from one place.
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

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 for full version history.

🎯 Quick Start

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

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

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

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

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

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

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

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

// 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

All responses follow this standardized format:

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

{
    "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

{
    "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

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

Exception	Status Code	Description
`ValidationException`	422	Validation errors
`AuthenticationException`	401	Unauthorized
`ModelNotFoundException`	404	Not found
`NotFoundHttpException`	404	Not found
`QueryException`	500	Server error (with debug info in development)
`HttpException`	Respective	HTTP status code

⚙️ Configuration Options

Response Structure

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

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

'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

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

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

use ApiResponse\Services\ResponseCompressionService;

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

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

<?php

namespace Tests\Feature;

use Tests\TestCase;
use App\Models\User;

class UserApiTest extends TestCase
{
    public function test_can_get_users()
    {
        $response = $this->getJson('/api/users');

        $response->assertStatus(200)
                ->assertJsonStructure([
                    'success',
                    'message',
                    'data',
                    'meta',
                    'timestamp'
                ])
                ->assertJson([
                    'success' => true,
                    'message' => 'Users retrieved successfully'
                ]);
    }

    public function test_can_create_user()
    {
        $userData = [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'password' => 'password123'
        ];

        $response = $this->postJson('/api/users', $userData);

        $response->assertStatus(201)
                ->assertJson([
                    'success' => true,
                    'message' => 'User created successfully'
                ]);
    }

    public function test_validation_errors()
    {
        $response = $this->postJson('/api/users', []);

        $response->assertStatus(422)
                ->assertJson([
                    'success' => false,
                    'message' => 'Validation failed'
                ])
                ->assertJsonStructure([
                    'errors' => [
                        'name',
                        'email',
                        'password'
                    ]
                ]);
    }
}

📊 Complete Example

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use ApiResponse\Traits\ApiResponseTrait;
use Illuminate\Validation\ValidationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;

class UserController extends Controller
{
    use ApiResponseTrait;

    public function index()
    {
        try {
            $users = User::paginate(10);
            return $this->paginatedResponse($users, 'Users retrieved successfully');
        } catch (\Exception $e) {
            return $this->serverErrorResponse('Failed to retrieve users');
        }
    }

    public function store(Request $request)
    {
        try {
            $validated = $request->validate([
                'name' => 'required|string|max:255',
                'email' => 'required|email|unique:users',
                'password' => 'required|min:8',
            ]);

            $user = User::create($validated);
            return $this->createdResponse($user, 'User created successfully');
        } catch (ValidationException $e) {
            return $this->validationErrorResponse($e->errors(), 'Validation failed');
        } catch (\Exception $e) {
            return $this->serverErrorResponse('Failed to create user');
        }
    }

    public function show($id)
    {
        try {
            $user = User::findOrFail($id);
            return $this->resourceResponse($user, 'User retrieved successfully');
        } catch (ModelNotFoundException $e) {
            return $this->notFoundResponse('User not found');
        }
    }

    public function update(Request $request, $id)
    {
        try {
            $user = User::findOrFail($id);
            $validated = $request->validate([
                'name' => 'sometimes|string|max:255',
                'email' => 'sometimes|email|unique:users,email,' . $id,
            ]);

            $user->update($validated);
            return $this->successResponse($user, 'User updated successfully');
        } catch (ModelNotFoundException $e) {
            return $this->notFoundResponse('User not found');
        } catch (ValidationException $e) {
            return $this->validationErrorResponse($e->errors(), 'Validation failed');
        }
    }

    public function destroy($id)
    {
        try {
            $user = User::findOrFail($id);
            $user->delete();
            return $this->successResponse(null, 'User deleted successfully');
        } catch (ModelNotFoundException $e) {
            return $this->notFoundResponse('User not found');
        }
    }
}

Testing this package

composer install
composer test           # run PHPUnit
composer format:check   # Laravel Pint
composer analyse        # PHPStan

Enterprise & production

For production use, enable request IDs and error codes in config; apply rate limiting and set APP_DEBUG=false.

🤝 Contributing

Please see CONTRIBUTING.md for development setup, code style, and pull request guidelines.

Security

If you discover a security vulnerability, please see SECURITY.md.

Changelog

See CHANGELOG.md for version history.

📄 License

This package is open-sourced software licensed under the MIT license.

🆘 Support

Issues: GitHub Issues
Documentation: Full Documentation

🙏 Acknowledgments

Laravel team for the amazing framework
All contributors who help improve this package
The open-source community for inspiration and feedback

Laravel API Response – A generic package for standardized API responses.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
config		config
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
composer.json		composer.json
composer.lock		composer.lock
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml		phpunit.xml
pint.json		pint.json

License

anyo-lab/api-response

Folders and files

Latest commit

History

Repository files navigation

Laravel API Response

🚀 Features

📋 Requirements

🔧 Installation

Via Composer

Manual Installation

⚙️ Configuration

Production readiness

Upgrading / Breaking changes

🎯 Quick Start

Basic Usage

📖 Usage Methods

Method 1: Service Injection

Method 2: Trait Usage

Method 3: Facade Usage

Method 4: Response Macros

Method 5: Global Helper Functions

Method 6: Resource Classes

📤 Response Methods

Success Responses

Error Responses

📋 Response Format

Success Response

Error Response

Pagination Response

🛡️ Exception Handling

⚙️ Configuration Options

Response Structure

Default Messages

Other Options

🔄 Advanced Features

Middleware Support

API Versioning

Response Compression

Performance Monitoring

🧪 Testing

📊 Complete Example

Testing this package

Enterprise & production

🤝 Contributing

Security

Changelog

📄 License

🆘 Support

🙏 Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages