PHPackages philiprehberger/laravel-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. [HTTP & Networking](/categories/http) 4. / 5. philiprehberger/laravel-api-versioning ActiveLibrary[HTTP & Networking](/categories/http) philiprehberger/laravel-api-versioning ====================================== Laravel middleware for API versioning with multi-source resolution from headers, Accept vendor types, and URL path segments v1.2.0(2mo ago)160MITPHPPHP ^8.2CI passing Since Mar 6Pushed 1mo agoCompare [ Source](https://github.com/philiprehberger/laravel-api-versioning)[ Packagist](https://packagist.org/packages/philiprehberger/laravel-api-versioning)[ Docs](https://github.com/philiprehberger/laravel-api-versioning)[ GitHub Sponsors](https://github.com/philiprehberger)[ RSS](/packages/philiprehberger-laravel-api-versioning/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (18)Versions (8)Used By (0) Laravel API Versioning ====================== [](#laravel-api-versioning) [![Tests](https://github.com/philiprehberger/laravel-api-versioning/actions/workflows/tests.yml/badge.svg)](https://github.com/philiprehberger/laravel-api-versioning/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/781dc0064b345bee6f752727bd6d898e6bce342b0621752983a99e027b48dac6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69707265686265726765722f6c61726176656c2d6170692d76657273696f6e696e672e737667)](https://packagist.org/packages/philiprehberger/laravel-api-versioning)[![Last updated](https://camo.githubusercontent.com/5987c55260ec249fe75f32f7d0e56d43607d9b2d7dfdbb0636ca17ab76ee401d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f7068696c69707265686265726765722f6c61726176656c2d6170692d76657273696f6e696e67)](https://github.com/philiprehberger/laravel-api-versioning/commits/main) Laravel middleware for API versioning with multi-source resolution from headers, Accept vendor types, and URL path segments. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11 or 12 Installation ------------ [](#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 ----- [](#usage) ### Configuration [](#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 [](#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 [](#accessing-the-current-version) ``` use PhilipRehberger\ApiVersioning\ApiVersion; $version = ApiVersion::current($request); // e.g. 'v2' ``` ### Version Resolution Priority [](#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 --- [](#api) Method / ConceptDescription`ApiVersion::current(Request $request)`Get the resolved API version for the current request`ApiVersion::aliases()`Get the configured version aliases as an associative array`ApiVersion::resolveAlias(string $alias)`Resolve an alias to its version string, or `null` if not found`ApiVersion::isDeprecated(string $version)`Check whether a version is deprecated (in `deprecated_versions` or not the `latest_version`)`ApiVersion` middlewareResolves version (with alias support), sets request attribute, adds response headers`X-API-Version` response headerThe resolved version for each request`X-API-Deprecated` response header`true` / `false` — whether this version is deprecated### Version Aliases [](#version-aliases) Map friendly names to version strings so clients can request `latest` or `stable` instead of a specific version number: ``` // config/api-versioning.php 'aliases' => [ 'latest' => 'v2', 'stable' => 'v1', ], ``` When the middleware resolves a version that matches an alias key, it transparently replaces it with the target version. For example, sending `X-API-Version: latest` is treated as `X-API-Version: v2`. You can also resolve aliases programmatically: ``` use PhilipRehberger\ApiVersioning\ApiVersion; ApiVersion::aliases(); // ['latest' => 'v2', 'stable' => 'v1'] ApiVersion::resolveAlias('latest'); // 'v2' ApiVersion::resolveAlias('unknown'); // null ``` ### Deprecation Checks [](#deprecation-checks) Check whether a version is deprecated programmatically: ``` use PhilipRehberger\ApiVersioning\ApiVersion; ApiVersion::isDeprecated('v1'); // true if v1 is in deprecated_versions or not latest_version ApiVersion::isDeprecated('v2'); // false if v2 === latest_version ``` ### SemVer-Style Versions [](#semver-style-versions) In addition to the simple `v1`, `v2` form, the URL path and Accept header resolvers also match SemVer-style versions like `v1.2`, `v1.2.3`, etc. List them in `supported_versions` to enable: ``` 'supported_versions' => ['v1', 'v1.2', 'v1.2.3', 'v2'], ``` ``` GET /api/v1.2.3/users Accept: application/vnd.api.v1.2.3+json ``` ### Custom Accept Header Pattern [](#custom-accept-header-pattern) Override the default `application/vnd.{vendor_name}.{version}+json` matcher with a custom regex via `accept_header_pattern`. The first capture group must contain the version string: ``` // config/api-versioning.php 'accept_header_pattern' => '/application\/json;\s*version=(v\d+(?:\.\d+){0,2})/', ``` ``` Accept: application/json; version=v2 ``` When `accept_header_pattern` is `null`, the default vendor type pattern is used. ### Response Headers [](#response-headers) HeaderValuesMeaning`X-API-Version``v1`, `v2`, ...The resolved version for this request`X-API-Deprecated``true` / `false`Whether this version is deprecated### Unsupported Version Response (400) [](#unsupported-version-response-400) ``` { "error": { "code": "unsupported_api_version", "message": "API version 'v99' is not supported.", "supported_versions": ["v1", "v2"] } } ``` Development ----------- [](#development) ``` composer install vendor/bin/phpunit vendor/bin/pint --test vendor/bin/phpstan analyse ``` Support ------- [](#support) If you find this project useful: ⭐ [Star the repo](https://github.com/philiprehberger/laravel-api-versioning) 🐛 [Report issues](https://github.com/philiprehberger/laravel-api-versioning/issues?q=is%3Aissue+is%3Aopen+label%3Abug) 💡 [Suggest features](https://github.com/philiprehberger/laravel-api-versioning/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) ❤️ [Sponsor development](https://github.com/sponsors/philiprehberger) 🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages) 💻 [GitHub Profile](https://github.com/philiprehberger) 🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger) License ------- [](#license) [MIT](LICENSE) ### Health Score 42 — FairBetter than 89% of packages Maintenance88 Actively maintained with recent releases Popularity12 Limited adoption so far Community8 Small or concentrated contributor base Maturity51 Maturing project, gaining track record Bus Factor1 Top contributor holds 94.1% 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. ### Release Activity Cadence Every ~5 days Total 7 Last Release 81d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/cfd7d24cbbf32400fa13ce0bbe7a31edd2d66a6d4488eafdb3d64c5337bf0435?d=identicon)[philiprehberger](/maintainers/philiprehberger) --- Top Contributors [![philiprehberger](https://avatars.githubusercontent.com/u/8218077?v=4)](https://github.com/philiprehberger "philiprehberger (16 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") --- Tags middlewareapilaravelrestversioning ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/philiprehberger-laravel-api-versioning/health.svg) ``` [![Health](https://phpackages.com/badges/philiprehberger-laravel-api-versioning/health.svg)](https://phpackages.com/packages/philiprehberger-laravel-api-versioning) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.1M337](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 59156.3k11](/packages/api-platform-laravel)[shahghasiadil/laravel-api-versioning Elegant attribute-based API versioning solution for Laravel applications with built-in deprecation management and version inheritance 2915.0k](/packages/shahghasiadil-laravel-api-versioning)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[laragear/api-manager Manage multiple REST servers to make requests in few lines and fluently. 162.0k](/packages/laragear-api-manager) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)