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 6d 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 today

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 88% of packages

Maintenance77

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

377d 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

[spatie/laravel-fractal

An easy to use Fractal integration for Laravel applications

1.9k14.8M87](/packages/spatie-laravel-fractal)[rupadana/filament-api-service

A simple api service for supporting filamentphp

20399.6k7](/packages/rupadana-filament-api-service)[grazulex/laravel-apiroute

Complete API versioning lifecycle management for Laravel

1022.8k](/packages/grazulex-laravel-apiroute)[rickwest/laravel-wordpress-api

A Laravel read-only client for the WordPress REST API (v2)

3711.9k1](/packages/rickwest-laravel-wordpress-api)[shahghasiadil/laravel-api-versioning

Elegant attribute-based API versioning solution for Laravel applications with built-in deprecation management and version inheritance

2912.6k](/packages/shahghasiadil-laravel-api-versioning)[crenspire/laravel-whatsapp

Laravel WhatsApp Business API package

102.1k](/packages/crenspire-laravel-whatsapp)

PHPackages © 2026

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