Laravel API Toolkit

A professional Laravel package to help standardize API development in your applications. It handles standardized JSON responses, auto-formatting pagination, API versioning, and exception formatting.

Installation

You can install the package via composer:

composer require codersandip/laravel-api-toolkit

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="api-toolkit-config"

Configuration

This is the contents of the published config file:

return [
    'default_api_version' => 'v1',

    'response_structure' => [
        'status' => 'status',
        'message' => 'message',
        'data' => 'data',
        'meta' => 'meta',
        'pagination' => 'pagination',
        'errors' => 'errors',
    ],

    'pagination_enabled' => true,
];

Features and Usage

1. Standard API Responses

The package provides the HasApiResponse trait. Use it in your base Controller or specialized API controllers:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Codersandip\ApiToolkit\Traits\HasApiResponse;
use App\Models\User;

class UserController extends Controller
{
    use HasApiResponse;

    public function show($id)
    {
        $user = User::find($id);

        if (!$user) {
            return $this->error('User not found', 404);
        }

        return $this->success($user, 'User fetched successfully');
    }
}

Success Response Format:

{
  "status": true,
  "message": "User fetched successfully",
  "data": {
      "id": 1,
      "name": "Jane Doe"
  },
  "meta": {
      "api_version": "v1"
  }
}

2. Auto Pagination Formatting

To format pagination seamlessly, use the ApiPagination trait:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Codersandip\ApiToolkit\Traits\ApiPagination;
use App\Models\User;

class UserListController extends Controller
{
    use ApiPagination;

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

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

Pagination Response Format:

{
  "status": true,
  "message": "Users retrieved successfully",
  "data": [
      // user objects
  ],
  "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 100,
      "last_page": 10
  }
}

3. Request Validation Helper

Use the generic ApiRequest to automatically output standardized JSON errors when validation fails (instead of HTML redirect or standard Laravel format).

<?php

namespace App\Http\Requests;

use Codersandip\ApiToolkit\Http\Requests\ApiRequest;

class StoreUserRequest extends ApiRequest
{
    public function authorize()
    {
        return true;
    }

    public function rules()
    {
        return [
            'name' => 'required|string',
            'email' => 'required|email|unique:users',
        ];
    }
}

Validation Error Response:

{
  "status": false,
  "message": "Validation Failed",
  "errors": {
      "email": [
          "The email has already been taken."
      ]
  }
}

4. API Versioning

The API version is automatically guessed from URL segments like /api/v1/users or falls back to your configuration default. You can get the current API version statically or through a helper:

use Codersandip\ApiToolkit\Facades\ApiVersion;

$version = ApiVersion::current();
// or
$version = api_version();

5. Standard Exception Formatting

You can delegate Exception rendering directly to the toolkit by modifying app/Exceptions/Handler.php or bootstrap/app.php depending on your Laravel version.

Laravel 11+:

// bootstrap/app.php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Codersandip\ApiToolkit\Exceptions\ApiToolkitExceptionHandler;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->render(function (Throwable $e, $request) {
            if ($request->is('api/*')) {
                return Codersandip\ApiToolkit\Exceptions\ApiToolkitExceptionHandler::render($e);
            }
        });
    })->create();

Testing

composer test

or

vendor/bin/phpunit

License

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