befuture/api-response

A lightweight and standardized API JSON response package for Laravel and standalone PHP projects.

Features

• Unified JSON response structure for success and error cases
• HTTP status code / internal code / message / data / meta fields
• Auto-discovery support for Laravel
• Standalone PHP usage via factory class
• Fully tested with PHPUnit
• GitHub Actions CI workflow included

Example JSON Structure

{
  "success": true,
  "code": "OK",
  "message": "Operation completed successfully.",
  "data": {
    "id": 1,
    "name": "Example"
  },
  "meta": {
    "request_id": "abc-123",
    "runtime_ms": 12
  }
}

Installation

composer require befuture/api-response

If the package is not published on Packagist yet, you may load it via VCS repository inside your composer.json.

Laravel Integration

The package supports Laravel auto-discovery.
If you prefer manual registration:

// config/app.php
'providers' => [
    BeFuture\ApiResponse\ApiResponseServiceProvider::class,
],

Optional Facade:

'aliases' => [
    'ApiResponse' => BeFuture\ApiResponse\Facades\ApiResponse::class,
],

Usage

use BeFuture\ApiResponse\ApiResponse;

// Success response
return ApiResponse::success(
    data: ['id' => 1],
    message: 'Success'
);

// Error response
return ApiResponse::error(
    message: 'An error occurred.',
    code: 'UNEXPECTED_ERROR',
    httpStatus: 500
);

// Validation error
return ApiResponse::validationError($validator->errors()->toArray());

Framework-Independent Usage

use BeFuture\ApiResponse\ApiResponseFactory;

$factory = new ApiResponseFactory();

$responseArray = $factory->success(
    data: ['foo' => 'bar'],
    message: 'OK'
);

header('Content-Type: application/json');
http_response_code($responseArray['_status']);
echo json_encode($responseArray['body']);

Running Tests

composer install
vendor/bin/phpunit

License

This project is licensed under the MIT License.
See LICENSE for details.