PHP code example of square / vermillion

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

square / vermillion example snippets

# routes/api.php

/*
 * Desired URL format: /api/v3/hello-world, etc.
 */
Route::prefix('/api')->group(function ($router) {

   // Start a group of versioned routes.
    $router->versioned()->group(function ($router) {

        // Define the base route. The specified controller-action will be used from min version to right before next...

        Route::get('/users', [UserController::class, 'list'])
          ->name('users.list')
          ->apiVersion('2', [UserController::class, 'listWithImplicitDefaults']) // Another controller used for v2+
          ->apiVersion('5', [UsersController::class, 'listViaCursorPagination']); // ...and another controller for v5+.

        // This other endpoint is only available v3+
        Route::post('/insights', $router->versioning()->unsupported()) // Default to "not supported" response (404)
          ->name('insights')
          ->apiVersion('3', [StatsController::class, 'insights']); // ...then goes to working controller for v3+
    });
});

# During an /api/v3/insights request
route('users.list');  #=> /api/v3/users

# Generate URL with specific version:
route('users.list', ['apiVersion' => '4']); #=> /api/v4/users

class InfoController
{
    public function list(Request $request, ApiVersion $apiVersion)
    {
        /*
         * Decide business logic based on API version...
         */
        if ($apiVersion->gte('4')) {
            // ...
        }

        if ($apiVersion->lte('6')) {
            // ...
        }

        if ($apiVersion->eq('7')) {
            // ...
        }

    }
}

class UserResource extends JsonResource
{
     use WithReverseMigrations;

     /**
      * This must return the API response body of the max version you support.
      */
     public function toLatestArray($request)
     {
        return [
            'display_name' => $this->resource->name,
            'full_name' => $this->resource->full_name,
            'age' => $this->resource->age,
            'friends' => $this->whenLoaded($this->resource->friends, fn() ...),
        ];
     }

     /**
      * Override this method to specify the "reverse-migrations" 
      * responsible for rolling back the latest API response body, 
      * one iteration at at ime.
      */
     protected static function reverseMigrations(VersionedSet $migrations)
     {
           $migrations
               ->for('5', self::addBackFirstAndLastName(...))
               ->for('3', self::friendsWasNotNullable(...))
     }

     protected static function addBackFirstAndLastName(array $data, UserResource $resource, $request)
     {
           unset($data['full_name']);
           return array_merge(
               $data,
               [
                   'first_name' => $resource->user->first_name,
                   'last_name' => $resource->user->last_name,
               ],
           );
     }

     protected static function friendsWasNotNullable(array $data, UserResource $resource, $request)
     {
        return array_merge(
              $data,
              [
                 'friends' => $resource->user->friends ?? [],
              ],
        );
     }
}

// app/Exceptions/Handler.php

namespace App\Exceptions;

use Square\Vermillion\Exceptions\VersionMissingException;

class Handler extends ExceptionHandler
{
    ...
    
    public function register()
    {
        $this->renderable(function (VersionMissingException $e) {
            return response([
                // Whatever you see fit.
            ])->setStatusCode(400);
        });
    }
}

// config/versioning.php

return [
  'scheme' => App\Http\Versioning\MyCustomScheme::class,
];

// config/versioning.php

return [
  'normalizer' => App\Http\Versioning\MyCustomNormalizer::class,
];

// Create a new VersionedSet
$set = app(VersioningManager::class)->versionedSet();

$set->for('1', new LegacyDoer()); // The original variation.
$set->for('3', new DifferentDoer()); // We made things a little different starting v3 but not in a very BC way.
$set->for('5', new BetterDoer()); // We made things a lot better starting v5, but it again e don't support this version.

php artisan vendor:publish