README

A clean and elegant Laravel package that provides a consistent and customizable structure for your API responses. Perfect for building maintainable, testable, and user-friendly APIs.

✨ Features

• ✅ Consistent JSON response format
• ✅ Localization via Accept-Language header (optional middleware)
• ✅ Built-in support for:
  • Collections with or without pagination
  • Single models/resources
  • Simple messages
  • Form request validation errors
• ✅ Laravel Responsable support
• ✅ Customizable success/error codes and messages
• ✅ Full test coverage with Pest
• ✅ Easy to use and integrate
• ✅ Designed for Laravel 11+

📦 Installation

composer require mahmoud-almalah/laravel-api-helpers -W

No need to register the service provider if you’re using Laravel 5.5+ (package auto-discovery is enabled).

⚙️ Configuration

You may optionally publish the config if you need to customize success/error codes or messages:

php artisan vendor:publish --tag=laravel-api-platform-config

🚀 Usage

✅ CollectionResponse

Returns a list of items with optional pagination metadata.

use MahmoudAlmalah\LaravelApiHelpers\Responses\CollectionResponse;
use App\Http\Resources\UserResource;

return new CollectionResponse(
    key: 'users',
    collection: UserResource::collection($users), // Collection or Paginator
    meta: $users instanceof \Illuminate\Contracts\Pagination\Paginator ? $users : null,
    message: 'Users retrieved successfully'
);

✅ ModelResponse

Wrap a single Eloquent model using a Laravel Resource.

use MahmoudAlmalah\LaravelApiHelpers\Responses\ModelResponse;
use App\Http\Resources\UserResource;

return new ModelResponse(
    key: 'user',
    resource: new UserResource($user),
    message: 'User fetched successfully'
);

✅ MessageResponse

Send a message-only response with optional data.

use MahmoudAlmalah\LaravelApiHelpers\Responses\MessageResponse;

return new MessageResponse(
    data: ['additional' => 'info'],
    message: 'Operation completed'
);

❌ FormRequestResponse

Use this for form validation errors (typically in custom validation handler).

use MahmoudAlmalah\LaravelApiHelpers\Responses\FormRequestResponse;

return new FormRequestResponse($validator->errors()->toArray());

Or you can just extend your form request from BaseRequest:

use MahmoudAlmalah\LaravelApiHelpers\Requests\BaseRequest;

class UserRequest extends BaseRequest
{
    public function rules(): array
    {
        return [/* ... */];
    }
}

🌐 Localization Middleware

You can enable automatic localization of your API responses based on the Accept-Language request header using the ApiLocalizationMiddleware.

✅ Enable Localization

To activate the middleware globally for your API, first publish the config file:

php artisan vendor:publish --tag=laravel-api-platform-config

Then update the localization settings in config/laravel-api-platform.php:

'localization' => [
    'status' => env('API_LOCALIZATION_STATUS', true), // Enable or disable localization
    'locales' => ['en', 'ar'], // Supported locales
],

✅ Environment Variables

You can also set the localization settings using environment variables in your .env file:

API_LOCALIZATION_STATUS=true

If enabled, the package will automatically register a middleware that sets the app locale (and number formatting) based on the Accept-Language header:

Accept-Language: ar

You can also manually assign the middleware to specific routes if preferred:

Route::middleware(['api-localization'])->get('/demo', fn () => response()->json([
    'locale' => app()->getLocale(),
]));

The middleware automatically uses Laravel’s localization and number formatting services to ensure consistent responses based on language.

✅ Output Format

All responses follow this consistent format:

{
  "status": true,
  "message": "Users retrieved successfully",
  "data": {
    "users": [/* ... */]
  },
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "has_more_pages": true
  }
}

• status: true for success, false for errors
• message: human-readable message
• data: payload
• meta: only shown when pagination is present

✅ Testing

This package comes with full test coverage using Pest.

composer test

🛠 Development Tools

# Code style
composer lint

# Static analysis
composer test:types

# Rector refactoring
composer refacto

# Full test suite
composer test

📂 Directory Structure

src/
├── Helpers/
│   ├── ApiResponseHelpers.php
│   Middleware/
│   ├── ApiLocalizationMiddleware.php
├── Responses/
│   ├── CollectionResponse.php
│   ├── ModelResponse.php
│   ├── MessageResponse.php
│   └── FormRequestResponse.php
├── Requests/
│   ├── BaseRequest.php
└── Providers/
    └── LaravelApiHelpersServiceProvider.php

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines for more information.

📄 License

The MIT License (MIT). See LICENSE for more information.