PHPackages                             juliomotol/lapiv - 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. juliomotol/lapiv

ActiveLibrary[API Development](/categories/api)

juliomotol/lapiv
================

API versioning for Laravel made easy

v3.2.0(2y ago)238.2k2MITPHPPHP ^8.0

Since Sep 19Pushed 2y ago1 watchersCompare

[ Source](https://github.com/juliomotol/lapiv)[ Packagist](https://packagist.org/packages/juliomotol/lapiv)[ Docs](https://github.com/juliomotol/lapiv)[ RSS](/packages/juliomotol-lapiv/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (6)Dependencies (7)Versions (9)Used By (0)

Lapiv
=====

[](#lapiv)

[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Latest Version on Packagist](https://camo.githubusercontent.com/eb8864e691cf96ad1d45c867e135eae7337d28b71a3b88ea31d515ba8e4bc928/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a756c696f6d6f746f6c2f6c617069762e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliomotol/lapiv)[![Total Downloads](https://camo.githubusercontent.com/f78e03949a5f3a818578a739ad2542d0b83916e4ad6b618759ba82f80ceeaae4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a756c696f6d6f746f6c2f6c617069762e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/juliomotol/lapiv)

> ## This package is **feature locked**
>
> [](#this-package-is-feature-locked)
>
> With the recent developments in PHP, Laravel and its community of packages, it has been easier than ever to manage routes for versioned APIs.
>
> We have found better ways to do what this package does in a much cleaner way. We suggest for you to take a look at [spatie/laravel-route-attributes](https://github.com/spatie/laravel-route-attributes) or [spatie/laravel-route-discovery](https://spatie.be/docs/laravel-route-discovery/v1/introduction).
>
> With that, we will still continue to provide support for future PHP/Laravel updates until any major breakage.

A Small Laravel package for a simple and easy API versioning.

Lapiv simply stands for (L)aravel (API) (V)ersioning.

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

[](#installation)

You can install the package via composer:

```
composer require juliomotol/lapiv
```

Config
------

[](#config)

KeyDefault ValueDescriptiondefault`"uri"`The versioning method. Supports: "uri", "query\_string".methods.uri.prefix`"v{version}"`The prefix for uri based versioning. (NOTE: Always include the "version" parameter in the prefix)methods.query\_string.key`"v"`The query string key name for determining the version> If you want to make changes in the configuration you can publish the config file using:
>
> ```
> php artisan vendor:publish --provider="JulioMotol\Lapiv\LapivServiceProvider"
>
> ```

Setup
-----

[](#setup)

Now the juicy part, we'll walk you through how to setup versioned Controllers.

### `FooV1Controller.php`

[](#foov1controllerphp)

This is very much like your standard controller. Nothing special here really. All action methods must be declared here e.g. `index`, `create`, `show`, etc.

```
namespace App\Http\Controllers\Api\Foo;

use App\Http\Controllers\Controller;

class FooV1Controller extends Controller
{
    public function index()
    {
        return response()->json(['message' => 'This is Foo V1']);
    }
}
```

### `FooGatewayController.php`

[](#foogatewaycontrollerphp)

Now the good stuff. This controller **MUST** extend `\JulioMotol\Lapiv\GatewayController` in order for this whole thing to work. This will be in charge of dispatching the requests based on the requested version. Let's take a look inside.

```
namespace App\Http\Controllers\Api\Foo;

use JulioMotol\Lapiv\GatewayController;

class FooGatewayController extends GatewayController
{
    protected array $apiControllers = [
        FooV1Controller::class, // The first version of you API endpoint.
        // Preceeding version implementations...
    ];
}
```

> The order in `$apiControllers` is critical. The first controller declared will be our `v1`, then will be `v2`, and so on.

### Routing

[](#routing)

With our controllers ready to go, lets create our route. Go to `routes/api.php`.

```
/**
 * Registers a versioned API endpoint.
 *
 * Router::lapiv($callback = null)
 *
 * @param $callback
 */
Route::lapiv(function () {
    Route::get('/foo', [FooGatewayController::class, 'index']);
    Route::get('/bar', [BarGatewayController::class, 'index']);
});
```

Notice we didn't point to the `[FooV1Controller::class, 'index']`. As we've said, the `FooGatewayController` will be doing much of the heavy work, so we'll just call that instead.

When you run `php artisan route:list` you should see this.

MethodURIActionGET|HEADapi/v{version}/fooApp\\Http\\Controllers\\Api\\FooGatewayController@indexGET|HEADapi/v{version}/barApp\\Http\\Controllers\\Api\\BarGatewayController@indexNow, when we try to go to `/api/v1/foo`, it should be handled by `FooV1Controller`.

### Bumping a version

[](#bumping-a-version)

When your ready to bump your API version to v2, Simply add a new `FooV2Controller` and dont forget to add that to `FooGatewayController`'s `$apiControllers`.

Versioning Methods
------------------

[](#versioning-methods)

This package supports 2 types of API Versioning methods, `uri` and `query_string`.

### `uri` Method

[](#uri-method)

This is the default of the versioning method. Here, the API version will be declared in the uri path (e.g. `example.com/api/v1/foo`).

In the config, you can change the prefix for the uri.

```
"methods" => [
    "uri" => [
        "prefix" => '/version-{version}' // will generate `example.com/api/version-1/foo`
    ]
]
```

> Don't forget to add the `version` parameter in the prefix.

### `query_string` Method

[](#query_string-method)

Here, the API version will be declared in the query string (e.g. `example.com/api/foo?v=1`).

In the config, you can change the query string key.

```
"methods" => [
    "query_string" => [
        "key" => 'version' // will accept `example.com/api/foo?version=1`
    ]
]
```

### Want to handle your own versioning method?

[](#want-to-handle-your-own-versioning-method)

You can define how you want to handle versioning your APIs by extending `JulioMotol\Lapiv\Drivers\BaseDriver`:

```
use JulioMotol\Lapiv\Drivers\BaseDriver;
use Illuminate\Support\Facades\Request;

class HeaderDriver extends BaseDriver
{
    public function getVersion(): string|int
    {
        $headerValue = Request::header($methodOptions['key']) ?? null;
        $matches = [];

        preg_match('/application\/vnd\.my_application\.v(\d*)\+json/', $headerValue, $matches);

        return $matches[1] ?? null;
    }
}
```

> You can also handle routing by overriding the `routeGroup()` method in the `BaseDriver`.

Then add your new API driver in your `AppServiceProvider::boot()`:

```
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        ApiVersioningManager::extend('header', fn () => new HeaderDriver());
    }
}
```

And finally, use your new driver in the `config/lapiv.php`

```
    'default' => 'header', // the value here will be the first parameter you've set in ApiVersioningManager::extend()
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Julio Motol](https://github.com/juliomotol)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Laravel Package Boilerplate
---------------------------

[](#laravel-package-boilerplate)

This package was generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com).

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity65

Established project with proven stability

 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.

###  Release Activity

Cadence

Every ~215 days

Recently: every ~295 days

Total

7

Last Release

776d ago

Major Versions

v1.x-dev → v2.0.02021-01-09

v2.0.0 → v3.0.02022-04-18

PHP version history (3 changes)v1.0.0PHP ^7.1

v2.0.0PHP ^7.3|^8.0

v3.0.0PHP ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/21353103?v=4)[Julio Motol](/maintainers/juliomotol)[@juliomotol](https://github.com/juliomotol)

---

Top Contributors

[![juliomotol](https://avatars.githubusercontent.com/u/21353103?v=4)](https://github.com/juliomotol "juliomotol (77 commits)")

---

Tags

apiapi-versioninglaravelapiversioningjuliomotollapiv

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/juliomotol-lapiv/health.svg)

```
[![Health](https://phpackages.com/badges/juliomotol-lapiv/health.svg)](https://phpackages.com/packages/juliomotol-lapiv)
```

###  Alternatives

[andreaselia/laravel-api-to-postman

Generate a Postman collection automatically from your Laravel API

1.0k586.2k3](/packages/andreaselia-laravel-api-to-postman)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[grazulex/laravel-apiroute

Complete API versioning lifecycle management for Laravel

1036.0k](/packages/grazulex-laravel-apiroute)[api-platform/laravel

API Platform support for Laravel

59126.4k6](/packages/api-platform-laravel)[dragon-code/laravel-json-response

Automatically always return a response in JSON format

1118.6k1](/packages/dragon-code-laravel-json-response)

PHPackages © 2026

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