sujon-ahmed / laravel-api-response

v1.0.0 2026-09-09 18:49 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

MIT

• Sujon Ahmed

Published on Packagist.org on 2026-09-09 18:57 UTC

README

A simple, clean, and reusable API response package for Laravel applications.

Standardize your API responses with a consistent structure for successful and failed requests.

✨ Features

• ✅ Simple success() response
• ❌ Simple error() response
• 📦 Reusable across Laravel projects
• 🚀 Laravel auto-discovery support
• 🔌 Facade support
• 🎯 Custom HTTP status codes
• 🧩 Clean and lightweight
• 🔒 No unnecessary dependencies

📋 Requirements

• PHP ^8.1
• Laravel 10.x, 11.x, 12.x, or 13.x

📦 Installation

Install the package using Composer:

composer require sujon-ahmed/laravel-api-response

The package supports Laravel's package auto-discovery, so no manual service provider registration is required.

🚀 Usage

Success Response

Use the ApiResponse facade to return a successful API response:

use SujonAhmed\ApiResponse\Facades\ApiResponse;

return ApiResponse::success(
    data: [
        'id' => 1,
        'name' => 'Sujon Ahmed',
    ],
    message: 'User fetched successfully'
);

Response:

{
  "success": true,
  "message": "User fetched successfully",
  "data": {
    "id": 1,
    "name": "Sujon Ahmed"
  }
}

The default HTTP status code is:

200 OK

Error Response

Return an error response using:

use SujonAhmed\ApiResponse\Facades\ApiResponse;

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

Response:

{
  "success": false,
  "message": "User not found",
  "data": null
}

HTTP status:

404 Not Found

Custom Status Code

You can provide any valid HTTP status code:

return ApiResponse::success(
    data: $user,
    message: 'User created successfully',
    status: 201
);

Response:

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": 1,
    "name": "Sujon Ahmed"
  }
}

HTTP status:

201 Created

🧱 API Response Structure

Success

{
  "success": true,
  "message": "Success",
  "data": {}
}

Error

{
  "success": false,
  "message": "Something went wrong",
  "data": null
}

This consistent structure makes API responses easier to consume from:

• React
• Next.js
• Vue
• Mobile applications
• Third-party integrations

🎯 Controller Example

<?php

namespace App\Http\Controllers;

use App\Models\User;
use SujonAhmed\ApiResponse\Facades\ApiResponse;

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

        if (!$user) {
            return ApiResponse::error(
                message: 'User not found',
                status: 404
            );
        }

        return ApiResponse::success(
            data: $user,
            message: 'User fetched successfully'
        );
    }
}

🔄 Typical API Flow

Request
   ↓
Controller
   ↓
Business Logic
   ↓
ApiResponse
   ↓
JSON Response

Example:

GET /api/users/1
        ↓
   UserController
        ↓
   Find User
        ↓
 ┌──────┴──────┐
 ↓             ↓
Found        Not Found
 ↓             ↓
success()    error()
 ↓             ↓
200 OK       404

🧪 Testing

Clone the repository:

git clone https://github.com/Sujon-Ahmed/laravel-api-response.git

Install dependencies:

composer install

Run the test suite:

composer test

Or, if your project uses Laravel's test runner:

php artisan test

🤝 Contributing

Contributions, issues, and feature requests are welcome.

1. Fork the repository
2. Create a feature branch

git checkout -b feature/my-feature

1. Commit your changes

git commit -m "Add my feature"

1. Push your branch

git push origin feature/my-feature

1. Open a Pull Request

📄 License

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

👨‍💻 Author

Sujon Ahmed

Full Stack Software Developer

• GitHub: https://github.com/Sujon-Ahmed
• LinkedIn: https://linkedin.com/in/sujonahmedriman/

⭐ Support

If this package helps you build cleaner Laravel APIs, consider giving the repository a ⭐ on GitHub.

Made with ❤️ for the Laravel community.