Implementing Versioning
- Posted May 2, 2018
- Addon Development
- Essentials
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.