README

API versioning support for Toporia Framework.

Installation

composer require toporia/api-versioning

Auto-Discovery

This package uses Toporia's Package Auto-Discovery system. After installation:

• Service Provider is automatically registered - no manual registration required
• Configuration is automatically discovered from extra.toporia.config in composer.json

To rebuild the package manifest manually:

php console package:discover

Setup

Publish Config (optional)

php console vendor:publish --provider="Toporia\ApiVersioning\ApiVersioningServiceProvider"
# Or with tag
php console vendor:publish --tag=api-config

Usage

1. Use Middleware

// routes/api.php

// Auto-detect version from request
$router->group(['middleware' => ['api.version']], function ($router) {
    $router->get('/users', [UserController::class, 'index']);
});

// Require specific version
$router->get('/v2-only', [NewController::class, 'index'])
    ->middleware(['api.version.exact:v2']);

// Require minimum version
$router->get('/modern', [ModernController::class, 'index'])
    ->middleware(['api.version.min:v2']);

2. Version-Specific Logic in Controllers

use Toporia\ApiVersioning\ApiVersion;

class UserController
{
    public function index()
    {
        if (ApiVersion::is('v1')) {
            // Legacy response format
            return response()->json(['users' => $users]);
        }

        if (ApiVersion::isAtLeast('v2')) {
            // New response with pagination
            return response()->json([
                'data' => $users,
                'meta' => ['total' => 100],
            ]);
        }
    }
}

3. Helper Functions

api_version();              // Get current version: 'v1'
api_version_is('v2');       // Check exact version
api_version_at_least('v2'); // Check minimum version

Version Detection

Version is detected from requests in this priority order:

1. Header (highest): X-API-Version: v2
2. Path: /api/v2/users
3. Accept Header: Accept: application/vnd.api.v2+json
4. Query (lowest): ?api_version=v2

Configuration

// config/api.php
return [
    'versioning' => [
        'enabled' => true,
        'default' => 'v1',
        'supported' => ['v3', 'v2', 'v1'], // newest first

        // Deprecated versions with sunset dates
        'deprecated' => [
            'v1' => '2025-12-31',
        ],

        'resolvers' => [
            'header' => ['enabled' => true, 'names' => ['X-API-Version']],
            'path' => ['enabled' => true, 'prefix' => 'api'],
            'query' => ['enabled' => false, 'param' => 'api_version'],
        ],
    ],
];

Response Headers

When using deprecated versions, responses include:

X-API-Version: v1
X-API-Deprecated: true
X-API-Sunset: 2025-12-31

License

MIT