tenantcloud/laravel-api-versioning

Simple Laravel API versioning implementation

v1.2.0 2024-04-25 12:25 UTC

Requires

• php: >=8.2
• illuminate/contracts: ^10.0
• illuminate/routing: ^10.0
• illuminate/support: ^10.0

Requires (Dev)

• nunomaduro/larastan: ^2.6
• orchestra/testbench: ^8.5
• pestphp/pest: ^2.8
• php-cs-fixer/shim: ~3.19.2
• phpstan/phpstan: ~1.10.21
• phpstan/phpstan-mockery: ^1.1
• phpstan/phpstan-phpunit: ^1.3
• phpstan/phpstan-webmozart-assert: ^1.2
• tenantcloud/php-cs-fixer-rule-sets: ~3.0.0

MIT

README

Laravel package for api versioning.

Do composer require tenantcloud/laravel-api-versioning to install the package.

Commands

Install dependencies: docker run -it --rm -v $PWD:/app -w /app composer install

Run tests: docker run -it --rm -v $PWD:/app -w /app php:8.1-cli vendor/bin/pest

Run php-cs-fixer on self: docker run -it --rm -v $PWD:/app -w /app composer cs-fix

Usage:

If no versions needed or endpoint is the same for any version use default Laravel route definition

// Api-Version: 1.0 -> CacToolCampaignController
// Api-Version: latest -> CacToolCampaignController
Route::post('cac/campaigns', [CacToolCampaignController::class, 'create']);

If route has versions - create some version rule

// Api-Version: 4.0 -> 404
// Api-Version: 3.0 -> CacToolCampaignTemplateController
// Api-Version: 1.0 -> CacToolCampaignTemplateController
Route::get('cac/campaigns/template', CacToolCampaignTemplateController::class)
->versioned('<=3.0');

If we made break change and want to provide new action for new version we should register two rules - one for old versions and new for new and future versions

// Api-Version: 3.0 -> CacToolCampaignTemplateController
// Api-Version: 4.0 -> CacToolCampaignTemplateForNewVersionController
// Api-Version: latest -> CacToolCampaignTemplateForNewVersionController
Route::get('cac/campaigns/template', CacToolCampaignTemplateController::class)
->versioned('<=3.0')
->versioned('>=4.0', [CacToolCampaignTemplateForNewVersionController::class, 'index'])

In some case we can get multiple break changes for some endpoint

// Api-Version: 3.0 -> CacToolCampaignTemplateController
// Api-Version: 4.0 -> error
// Api-Version: 5.0 -> CacToolCampaignVersion5Controller
// Api-Version: latest -> CacToolCampaignVersion5Controller
Route::get('cac/campaigns/template', CacToolCampaignTemplateController::class)
->versioned('<=3.0')
->versioned('>=5.0', [CacToolCampaignVersion5Controller::class, 'index'])

All resolves registered by APIVersioningServiceProvider::class