README

A lightweight Laravel package that provides reusable JSON response macros to keep your API responses consistent and developer-friendly.

Installation

composer require charlesuwaje/response-macros

Laravel will auto-discover the service provider. No manual registration needed.

Available Macros

Usage

use App\Models\User;
use Illuminate\Http\Request;

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

        return response()->paginated('Users retrieved successfully', $users->items(), [
            'total'        => $users->total(),
            'per_page'     => $users->perPage(),
            'current_page' => $users->currentPage(),
            'last_page'    => $users->lastPage(),
        ]);
    }

    public function store(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
        ]);

        $user = User::create($validated);

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

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

        if (! $user) {
            return response()->notFound('User not found');
        }

        return response()->success('User found', $user->toArray());
    }

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

        if (! $user) {
            return response()->notFound('User not found');
        }

        $user->delete();

        return response()->noContent();
    }
}

Response Format

Success:

{
    "status": "success",
    "message": "Users retrieved successfully",
    "data": []
}

Paginated:

{
    "status": "success",
    "message": "Users retrieved successfully",
    "data": [],
    "meta": {
        "pagination": {
            "total": 100,
            "per_page": 15,
            "current_page": 1,
            "last_page": 7
        }
    }
}

Error:

{
    "status": "error",
    "message": "Something went wrong",
    "data": {}
}

Validation error:

{
    "status": "validation_error",
    "message": "Validation failed",
    "errors": {
        "email": ["The email field is required."]
    }
}

Contributing

PRs and suggestions are welcome. If you find a bug or want to add new macros, open an issue or submit a pull request.