cleaniquecoders/laravel-api-version

Effortlessly manage your Laravel API versions with flexible, header-based versioning control.

v1.0.1 2024-11-03 23:26 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3

MIT

• Nasrul Hazim Bin Mohamad

• laravel
• Cleanique Coders
• laravel-api-version

README

Laravel API Version

Effortlessly manage your Laravel API versions with flexible, header-based versioning control.

Installation

You can install the package via composer:

composer require cleaniquecoders/laravel-api-version

You can publish the config file with:

php artisan vendor:publish --tag="laravel-api-version-config"

Usage

Configuration

This will create a config/api-version.php file where you can customize options like the default version, headers, version format, and the root namespace for versioned controllers.

Example configuration:

return [
    'default_version' => 'v1',
    'use_accept_header' => true,
    'custom_header' => 'X-API-Version',
    'accept_header_pattern' => '/application\/vnd\.\w+\+v(\d+(\.\d+)*)\+json/',
    'root_namespace' => 'App\Http\Controllers\Api',
];

Middleware Setup

The api.version middleware is registered automatically. This middleware allows for automatic version detection based on headers or explicit version specification in the route.

Defining Versioned Routes

Option 1: Header-Based Version Detection

To enable automatic version detection from headers, use the api.version middleware in your routes/api.php:

use Illuminate\Support\Facades\Route;

Route::middleware(['api', 'api.version'])->group(function () {
    Route::get('/example', 'ExampleController@index');
    // Additional routes here
});

This setup detects versions from the Accept or X-API-Version headers, dynamically routing requests to the correct versioned namespace.

Option 2: Explicitly Setting the Version

You can explicitly define a version for a route or route group by passing the version to the middleware. This approach bypasses header detection.

use Illuminate\Support\Facades\Route;

Route::middleware(['api', 'api.version:v1'])->group(function () {
    Route::get('/example', 'ExampleController@index');
    // Routes for v1
});

Route::middleware(['api', 'api.version:v2'])->group(function () {
    Route::get('/example', 'ExampleController@index');
    // Routes for v2
});

In this example:

• api.version:v1 directs routes in the group to the v1 namespace.
• api.version:v2 directs routes to the v2 namespace, ignoring headers.

Example Requests

Using Accept Header

curl -L -H "Accept: application/vnd.yourapp+v2+json" https://yourapp/api/example

Using Custom Header (X-API-Version)

curl -L -H "X-API-Version: 2" https://yourapp/api/example

Explicitly Versioned Route

If the route is explicitly defined as api.version:v2, no header is needed to access version 2.

Testing

Run the package tests:

composer test

Changelog

Please see CHANGELOG for details on recent updates.

Contributing

Please see CONTRIBUTING for contribution guidelines.

Security Vulnerabilities

Please review our security policy for reporting security issues.

Credits

• Nasrul Hazim Bin Mohamad
• All Contributors

License

The MIT License (MIT). See the License File for details.