mohamedhekal/apiforge

Laravel API kit: version negotiation, JSON envelopes, consistent error rendering, and route helpers

v0.1.0 2026-07-16 14:23 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• illuminate/validation: ^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.18
• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Mohamed Hekal

• php
• json
• rest
• errors
• api
• versioning
• laravel
• rest-api
• JSON-API
• laravel-package
• api-errors

Published on Packagist.org on 2026-07-16 14:34 UTC

README

Search terms: laravel, api, versioning, json, errors, rest, php, laravel-package, rest-api, api-errors, json-api.

Laravel API kit: version negotiation, JSON success/error envelopes, exception rendering, and Route::apiVersion() helpers.

Installation

composer require mohamedhekal/apiforge
php artisan vendor:publish --tag=apiforge-config

Versioned routes

use Hekal\ApiForge\Facades\ApiForge;
use Illuminate\Support\Facades\Route;

Route::apiVersion('v1', function () {
    Route::get('/orders', fn () => ApiForge::ok(['orders' => []]));
});
// GET /api/v1/orders

Middleware aliases: apiforge.version, apiforge.json.

Version can also come from X-API-Version or Accept: application/vnd.apiforge.v1+json.

Envelopes

{
  "data": { "id": 1 },
  "error": null,
  "meta": { "version": "v1", "request_id": "..." }
}

ApiForge::fail('Out of stock', 'out_of_stock', 409, ['sku' => 'A1']);
throw new \Hekal\ApiForge\Exceptions\ApiException('Nope', 'conflict', 409);

Validation / auth / 404 exceptions under API routes render into the same shape.

Composition

Pair with mohamedhekal/oncegate for Idempotency-Key on mutating routes. Rate limiting stays Laravel’s throttle middleware.

Limitations (v0.1)

• No OpenAPI generator yet
• Does not replace Form Requests or API Resources—use them inside controllers as usual
• Unsupported requested versions fall back to default (not 406)

Testing

composer install && composer test

License

MIT