venky/api-responder

Simple, standardized JSON API response library for Laravel

dev-main 2025-11-06 10:51 UTC

Requires

• php: ^8.0
• illuminate/http: ^9.0|^10.0|^11.0
• illuminate/pagination: ^9.0|^10.0|^11.0
• illuminate/support: ^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Venkatesh

README

A simple Laravel package that provides a standardized JSON response structure for APIs.

📦 Installation

composer require venky/api-responder

🚀 Usage

Basic Success Response

use Venky\ApiResponder\ApiResponse;

return ApiResponse::success($user, 'Fetched successfully');

Error Response

return ApiResponse::error('User not found', 404);

// With validation errors
return ApiResponse::error('Validation failed', 422, $validator->errors());

Paginated Response

$users = User::paginate(10);
return ApiResponse::paginated($users, 'Users fetched successfully');

🧾 Response Format

Success Response

{
  "status": "success",
  "code": 200,
  "message": "Fetched successfully",
  "data": {
    "id": 1,
    "name": "Venkatesh"
  }
}

Error Response

{
  "status": "error",
  "code": 404,
  "message": "User not found",
  "errors": []
}

Paginated Response

{
  "status": "success",
  "code": 200,
  "message": "Users fetched successfully",
  "data": [...],
  "pagination": {
    "total": 100,
    "count": 10,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 10
  }
}

📝 Example Controller Usage

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Venky\ApiResponder\ApiResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::find($id);
        
        if (!$user) {
            return ApiResponse::error('User not found', 404);
        }
        
        return ApiResponse::success($user, 'User fetched successfully');
    }
    
    public function index(Request $request)
    {
        $users = User::paginate(10);
        return ApiResponse::paginated($users, 'Users fetched successfully');
    }
}

🧪 Testing

Package Tests

composer test

Testing Locally in a Laravel Project

To test the package in a local Laravel project before publishing:

1. Add local repository (from your Laravel project directory):

   composer config repositories.api-responder path ../laravel-api-responder

2. Require the package:

   composer require venky/api-responder:dev-main

3. Use in your controller:

   use Venky\ApiResponder\ApiResponse;
   
   return ApiResponse::success($data, 'Success message');

📖 See TESTING_LOCALLY.md for detailed instructions and examples.

🧰 Future Ideas

• Add ApiResponse::fromException($e) for automatic exception handling
• Add custom middleware for auto-formatting all JSON responses
• Add config for default messages and response structure
• Support for custom response transformers

📄 License

MIT License - see LICENSE file for details.