PHPackages                             toporia/api-versioning - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. toporia/api-versioning

ActiveLibrary[API Development](/categories/api)

toporia/api-versioning
======================

API versioning support for Toporia Framework

00PHP

Since Dec 16Pushed 5mo agoCompare

[ Source](https://github.com/Minhphung7820/toporia-api-versioning)[ Packagist](https://packagist.org/packages/toporia/api-versioning)[ RSS](/packages/toporia-api-versioning/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Toporia API Versioning
======================

[](#toporia-api-versioning)

API versioning support for Toporia Framework.

Installation
------------

[](#installation)

```
composer require toporia/api-versioning
```

Auto-Discovery
--------------

[](#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
-----

[](#setup)

### Publish Config (optional)

[](#publish-config-optional)

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

Usage
-----

[](#usage)

### 1. Use Middleware

[](#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

[](#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

[](#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-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
-------------

[](#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
----------------

[](#response-headers)

When using deprecated versions, responses include:

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

```

License
-------

[](#license)

MIT

###  Health Score

17

—

LowBetter than 6% of packages

Maintenance50

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/1cc240e87c451f2dd614b87bb0d07039e4a20d8b391221c651172cf341e0b6cd?d=identicon)[Minhphung7820](/maintainers/Minhphung7820)

---

Top Contributors

[![Minhphung7820](https://avatars.githubusercontent.com/u/110077842?v=4)](https://github.com/Minhphung7820 "Minhphung7820 (3 commits)")

### Embed Badge

![Health badge](/badges/toporia-api-versioning/health.svg)

```
[![Health](https://phpackages.com/badges/toporia-api-versioning/health.svg)](https://phpackages.com/packages/toporia-api-versioning)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)