README

A package for transitioning HTTP requests and responses based on a version header.

Release updates to your API schema without breaking existing clients by creating Transition classes that transition the request and/or response to match the previously expected result. Each layer of transitions only needs to convert the current version to match the previous version, from there the request and response will be piped through the subsequent layers until they match the version requested in the Api-Version header.

Largely based on Stripe's API versioning article.

Requirements

• PHP 8.3+
• Laravel 12 or 13

Install

$ composer require bbrothers/http-transitions

The service provider is auto-discovered.

Middleware

In bootstrap/app.php, add the middleware globally or to a group:

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append: [
        Transitions\TransitionMiddleware::class,
    ]);
})

Publish Config

php artisan vendor:publish --tag=transitions-config

Usage

Add version numbers and an array of Transition classes to the transitions.php file.

return [
   'headerKey' => 'Api-Version',
   'transitions'    => [
       '20160101' => [
           FullNameToNameTransition::class,
           NameToFirstNameLastNameTransition::class,
           BirthDateTransition::class,
       ],
       '20150101' => [
           FirstNameLastNameToFullNameTransition::class,
       ],
   ],
]

Create a transition:

class NameToFirstNameLastNameTransition extends Transition
{
    public function transformResponse(Response $response): Response
    {
        $content = json_decode($response->getContent(), true);
        $content = array_diff_key(array_merge($content, $content['name']), ['name' => true]);

        return $response->setContent(json_encode($content));
    }
}

Transition Generators

$ php artisan make:transition NameToFirstNameLastNameTransition

Optionally, the --request-only or --response-only flags can be added to create a transform that only generates a transformRequest or transformResponse method respectively.

Change log

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.