Laravel API Versioning

Laravel middleware for API versioning with multi-source resolution from headers, Accept vendor types, and URL path segments.

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require philiprehberger/laravel-api-versioning

Laravel's package auto-discovery registers the service provider automatically.

Publish the config file:

php artisan vendor:publish --tag=api-versioning-config

This creates config/api-versioning.php.

Usage

Configuration

// config/api-versioning.php

return [
    'supported_versions'  => ['v1', 'v2'],
    'default_version'     => 'v1',
    'latest_version'      => 'v2',
    'deprecated_versions' => [],
    'vendor_name'         => 'myapp',
    'header'              => 'X-API-Version',
    'response_headers'    => true,
];

Registering the Middleware

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'api.version' => \PhilipRehberger\ApiVersioning\ApiVersion::class,
    ]);
})

Route::middleware('api.version')->group(function () {
    // ...
});

Accessing the Current Version

use PhilipRehberger\ApiVersioning\ApiVersion;

$version = ApiVersion::current($request); // e.g. 'v2'

Version Resolution Priority

1. X-API-Version request header
2. Accept header vendor type: application/vnd.{vendor_name}.{version}+json
3. URL path segment: /api/{version}/...
4. Configured default version

API

Response Headers

Unsupported Version Response (400)

{
    "error": {
        "code": "unsupported_api_version",
        "message": "API version 'v99' is not supported.",
        "supported_versions": ["v1", "v2"]
    }
}

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

License

MIT