1. Help
  2. Addon Development
  3. Modules
  4. Implementing Versioning

Implementing Versioning

Versioning Documentation

As of Pyro 3.5 most addons come with versioning built in right out of the box. You can easily implement versioning into your custom modules too. In this tutorial we will go over to how incorporate version management.


{{ img('local://help_center/implementing-versioning--index.jpg')|raw }}


Enable Versioning

First let's define the desired model(s) as being versionable. This is done via the $versionable property:

protected $versionable = true;

You can also define the stream as versionable in it's migration:

protected $stream = [
    'slug' => 'example',
     'versionable' => true,
];

Versions are not deleted when entries are trashed or deleted. This is designed behavior should catastrophic loss occur.

Defining Routes

Next let's define the routes used to manage versions. We will be using the routers built-in to the Streams Platform.

To get started use the VersionRouter router to automate defining routes for the version management:

VersionRouter::route(Addon $addon, $controller, $prefix = null, $base = '/versions');

The $addon is the instance of the addon that own's these routes. You can easily get this from your service provider (see below).

The $controller is your addon's controller for field or assignment management. We will talk about these later but they extend the base VersionsController class.

The $prefix is a path prefix that is helpful if the routes need to be prefixed for some reason. This is useful for example if you are allowing version management for multiple streams within a single addon. You can prefix each management area and use controllers for either stream this way.

Below is a trimmed down real-world example of the Pages module implementation of this routers:

<?php namespace Anomaly\PagesModule;

use Anomaly\Streams\Platform\Addon\AddonServiceProvider;
use Anomaly\PagesModule\Http\Controller\Admin\VersionsController;
use Anomaly\Streams\Platform\Version\VersionRouter;

class PagesModuleServiceProvider extends AddonServiceProvider
{

    /**
     * Map additional routes.
     *
     * @param VersionRouter $versions
     */
    public function map(VersionRouter $versions)
    {
        $versions->route($this->addon, VersionsController::class);
    }
}

Create Your Controller

Notice how we specified the controller for version management in the routers above. Let's go ahead and make that controller now.

Versions Controller

To create a versions controller simply extend the base Anomaly\Streams\Platform\Http\Controller\VersionsController controller with your own.

The only property that is required is the $model property which tells the controller which model to display versions for.

<?php namespace Anomaly\PagesModule\Http\Controller\Admin;

use Anomaly\PagesModule\Page\PageModel;

class VersionsController extends \Anomaly\Streams\Platform\Http\Controller\VersionsController
{

   /**
     * The versionable model.
     *
     * @var string
     */
    protected $model = PageModel::class;

}
Specifying Entry IDs

The versions router assumes an entry ID be present when accessing it's routes. For example: admin/pages/types/assignments/{stream}

Be sure to include the ID of the entry you wish to manage versions for in your button or link to access these controllers. Typically this is default behavior.

Below is how we do it in the pages module. This buttons definition is on the PageEntryFormBuilder which is the main form builder for any given page:

protected $buttons = [
    'versions',
    'cancel',
    'view' => [
        'enabled' => 'edit',
        'target'  => '_blank',
    ],
];

Notice the versions button is a registered button and no further configuration is needed by default.

At this point your implementation of versioning is done for 95% of use cases. Some addons may require additional overriding of methods on the controller or different button configuration to separate areas (see Variables Module example) but chances are you are ready to go! The loading of versions and tracking is automated for you.