PHPackages ejunker/laravel-api-evolution - 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. ejunker/laravel-api-evolution ActiveLibrary[API Development](/categories/api) ejunker/laravel-api-evolution ============================= Evolve your API while maintaining backwards compatibility. API versioning like Stripe. 0.1.4(1y ago)2176↓100%[3 PRs](https://github.com/ejunker/laravel-api-evolution/pulls)MITPHPPHP ^8.1CI passing Since Oct 11Pushed 1mo ago1 watchersCompare [ Source](https://github.com/ejunker/laravel-api-evolution)[ Packagist](https://packagist.org/packages/ejunker/laravel-api-evolution)[ Docs](https://github.com/ejunker/laravel-api-evolution)[ RSS](/packages/ejunker-laravel-api-evolution/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (12)Versions (9)Used By (0) Evolve your API while maintaining backwards compatibility. ========================================================== [](#evolve-your-api-while-maintaining-backwards-compatibility) [![Latest Version on Packagist](https://camo.githubusercontent.com/d0376cce6a96a1ea484f7142ae243b45bb0c3d837b9040c243c13ff68d044973/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656a756e6b65722f6c61726176656c2d6170692d65766f6c7574696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ejunker/laravel-api-evolution)[![GitHub Tests Action Status](https://camo.githubusercontent.com/69566e47579453d733a7afa7b665df772f3ade490a53a9429f37155ff0612ddb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f656a756e6b65722f6c61726176656c2d6170692d65766f6c7574696f6e2f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/ejunker/laravel-api-evolution/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/237cf7df6b7a10986f6d78970f71150d59e3080638061104725c4670d8c83598/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f656a756e6b65722f6c61726176656c2d6170692d65766f6c7574696f6e2f466978253230504850253230636f64652532307374796c652532306973737565733f6c6162656c3d636f64652532307374796c65)](https://github.com/ejunker/laravel-api-evolution/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/ac6a65d5332734a422f99a9192f3f6bed73b11b38e0c37d5133eb3b320bdec57/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f656a756e6b65722f6c61726176656c2d6170692d65766f6c7574696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ejunker/laravel-api-evolution) Laravel API Evolution is an API versioning library based on the idea of API evolution. It provides a way to make changes to your API way while maintaining backwards compatibility. Inspired by [Stripe's API versioning](https://stripe.com/blog/api-versioning) strategy. Users specify the desired version in a header and the request and response data will be modified to match the requested version. Installation ------------ [](#installation) You can install the package via composer: ``` composer require ejunker/laravel-api-evolution ``` You can run the installation command with: ``` php artisan api-evolution:install ``` The `api-evolution:install` command will create the `config/api-evolution.php` config file. You will need to add the middleware to your `api` middleware group in `app/Http/Kernel.php` or to the group/route that you want. ``` 'api' => [ // \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class, 'throttle:api', \Illuminate\Routing\Middleware\SubstituteBindings::class, \Ejunker\LaravelApiEvolution\ApiEvolutionMiddleware::class, ], ``` Usage ----- [](#usage) You can create an API migration using the command: ``` php artisan make:api-migration FirstLastName ``` This will create the file `app/Http/Migrations/FirstLastName.php` that you can edit to make the necessary changes to the request and/or response. Then you need to add it to the `config/api-evolution.php` file so that it runs when an old version is requested. The migrations listed for a version are the migrations needed to make it match the previous version. API Migrations -------------- [](#api-migrations) Each API migration file has several properties and methods that you can use: - `routeNames` - an array of route names that this migration will run for. You can use wildcards such as `api.v1.users.*` - `isApplicable()` - if `routeNames` does not give you enough flexibility, you can use this method to determine if the migration should run based on the `Request` - `migrateRequest()` - allows you to modify the `Request` so that it is compatible with the newer version - `migrateResponse()` - allows you to modify the `Response` so that it is the older version that was requested In addition to `routeNames` and `isApplicable()`, you can also specify the route names for a migration in the config file. ``` 'versions' => [ '2022-10-10' => [ new \App\Http\Migrations\FirstLastName(['api.v1.users.show']), ], '2022-10-05' => [ // first version ], ], ``` Binds ----- [](#binds) While API Migrations allow you to modify the `Request` and `Response`, sometimes it may be easier to use an entirely different FormRequest, JsonResource, or response Transformer. In those cases you can use a `Bind` to bind a different version into the container. In the `config/api-evolution.php` ``` 'versions' => [ '2022-10-10' => [ \App\Http\Migrations\FirstLastName::class new \Ejunker\LaravelApiEvolution\Bind( \App\Transformers\UserTransformer::class, \App\Transformers\UserTransformer_20221005::class, ), ], '2022-10-05' => [ // first version ], ], ``` In this example, if the user requested the `2022-10-05` version it would apply the `Bind` which would bind the old version of the file into the container so that it would be used. If the user requested the latest version `2022-10-10`then the `Bind` would not run and the latest version of the file would be used. Determine if a Migration Is Active ---------------------------------- [](#determine-if-a-migration-is-active) If you need to modify things other than Request/Response such as modifying a SQL query based on the version then you can use `ApiEvolution::isActive()`. For example, to know if the `FirstLastName` migration is active: `ApiEvolution::isActive(FirstLastName::class)` Response Headers ---------------- [](#response-headers) Several headers are added to the response: - `API-Version` - the version requested or the latest version if no specific version is requested - `API-Version-Latest` - if the version requested is not the latest version then this header will be added - `Deprecated` - if there are migrations or Binds that run for this endpoint then this header will be added to indicate that there is a newer version of this endpoint Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Eric Junker](https://github.com/ejunker) - [All Contributors](../../contributors) This package is based on the following: - [tomschlick/request-migrations](https://github.com/tomschlick/request-migrations) - [lukepolo/laravel-api-migrations](https://github.com/lukepolo/laravel-api-migrations) - [ds-labs/laravel-redaktor](https://github.com/ds-labs/laravel-redaktor) - [reindert-vetter/api-version-control](https://github.com/reindert-vetter/api-version-control) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 40 — FairBetter than 87% of packages Maintenance74 Regular maintenance activity Popularity15 Limited adoption so far Community10 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits 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 ~220 days Total 5 Last Release 424d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/94f5faf8e6d32349cbaf2ebf6cd84b0eb2565f44f3429950f0b06d626ef315bd?d=identicon)[ejunker](/maintainers/ejunker) --- Top Contributors [![ejunker](https://avatars.githubusercontent.com/u/4758?v=4)](https://github.com/ejunker "ejunker (30 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (22 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (16 commits)") --- Tags apilaravelversioningejunkerlaravel-api-evolution ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/ejunker-laravel-api-evolution/health.svg) ``` [![Health](https://phpackages.com/badges/ejunker-laravel-api-evolution/health.svg)](https://phpackages.com/packages/ejunker-laravel-api-evolution) ``` ### Alternatives [dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.0k7.8M55](/packages/dedoc-scramble)[grazulex/laravel-apiroute Complete API versioning lifecycle management for Laravel 1036.0k](/packages/grazulex-laravel-apiroute)[scalar/laravel Render your OpenAPI-based API reference 6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer Minimalistic token-based authentication for Laravel API endpoints. 8129.8k](/packages/ryangjchandler-bearer)[stechstudio/laravel-hubspot A Laravel SDK for the HubSpot CRM Api 2971.0k](/packages/stechstudio-laravel-hubspot)[rickwest/laravel-wordpress-api A Laravel read-only client for the WordPress REST API (v2) 3712.5k1](/packages/rickwest-laravel-wordpress-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)