tenantcloud/laravel-api-versioning

Simple Laravel API versioning implementation

v1.1.0 2024-01-15 14:59 UTC

Requires

• php: >=8.1
• 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

Interface	Default implementation	Description
ControllerDispatcher	VersionControllerDispatcher	Router dispatcher
RequestVersionParser	RequestHeaderVersionParser	Parse version from Illuminate\Http\Request object
ConstraintChecker	SemanticConstraintChecker	Constrain checker from TenantCloud\APIVersioning\Version\Version interface and array of rules
VersionParser	SemanticVersionParser	Version parser
StringConstraintParser	BuiltInStringConstraintParser	Parser from sting