Version
A CakePHP 4.x plugin that facilitates versioned database entities
Installation
Add the following lines to your application's composer.json:
"require": {
"josegonzalez/cakephp-version": "dev-master"
}
followed by the command:
composer update
Or run the following command directly without changing your composer.json:
composer require josegonzalez/cakephp-version:dev-master
Usage
In your app's config/bootstrap.php add:
Plugin::load('Josegonzalez/Version', ['bootstrap' => true]);
Usage
Run the following schema migration:
CREATE TABLE `version` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`version_id` int(11) DEFAULT NULL,
`model` varchar(255) NOT NULL,
`foreign_key` int(10) NOT NULL,
`field` varchar(255) NOT NULL,
`content` text NULL,
`created` datetime NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Note that the
contentfield must be nullable if you want to be able to version any nullable fields in your application.
You may optionally add a
version_idfield of typeintegerto the table which is being versioned. This will store the latest version number of a given page.
If you wish to create the table using cakephp/migrations then you will need to use a migration that looks something like this:
<?php
use Phinx\Migration\AbstractMigration;
class CreateVersions extends AbstractMigration
{
public function change()
{
$this->table('version')
->addColumn('version_id', 'integer', ['null' => true])
->addColumn('model', 'string')
->addColumn('foreign_key', 'integer')
->addColumn('field', 'string')
->addColumn('content', 'text', ['null' => true])
->addColumn('created', 'datetime')
->create();
}
}
Add the following line to your entities:
use \Josegonzalez\Version\Model\Behavior\Version\VersionTrait;
And then include the trait in the entity class:
class PostEntity extends Entity {
use VersionTrait;
}
Attach the behavior in the models you want with:
public function initialize(array $config) {
$this->addBehavior('Josegonzalez/Version.Version');
}
Whenever an entity is persisted - whether via insert or update - that entity is also persisted to the version table. You can access a given revision by executing the following code:
// Will contain a generic `Entity` populated with data from the specified version.
$version = $entity->version(1);
You can optionally retrieve all the versions:
$versions = $entity->versions();
Storing Additional Meta Data
cakephp-version dispatches an event Model.Version.beforeSave which you can optionally handle to attach additional meta-data about the version.
Add the necessary additional fields to your migration, for example:
CREATE TABLE `version` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`version_id` int(11) DEFAULT NULL,
`model` varchar(255) NOT NULL,
`foreign_key` int(10) NOT NULL,
`field` varchar(255) NOT NULL,
`content` text,
`created` datetime NOT NULL,
`custom_field1` varchar(255) NOT NULL, /* column to store our metadata */
`custom_field2` varchar(255) NOT NULL, /* column to store our metadata */
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Then define an event listener to handle the event and pass in additional metadata, for example:
use Cake\Event\Event;
use Cake\Event\EventListenerInterface;
class VersionListener implements EventListenerInterface {
public function implementedEvents() {
return array(
'Model.Version.beforeSave' => 'insertAdditionalData',
);
}
public function insertAdditionalData(Event $event) {
return [
'custom_field1' => 'foo',
'custom_field2' => 'bar'
];
}
}
Your event listener can then be attached in your project, for example:
use App\Event\VersionListener;
use Cake\Event\EventManager;
$VersionListener = new VersionListener();
EventManager::instance()->on($VersionListener);
Note that handling this event also allows you to modify/overwrite values generated by the plugin. This can provide useful functionality, but ensure that if your event listener returns array keys called version_id, model, foreign_key, field, content or created that this is the intended behavior.
Storing user_id as Meta Data
To store the user_id as additional meta data is easiest in combination with Muffin/Footprint. The above insertAdditionalData() method could then look like this:
/**
* @param \Cake\Event\Event $event
*
* @return array
*/
public function insertAdditionalData(Event $event)
{
$data = [
...
];
if ($event->data('_footprint')) {
$user = $event->data('_footprint');
$data += [
'user_id' => $user->id,
];
}
return $data;
}
Any controller with the FootprintAwareTrait used will then provide the _footprint data into the model layer for this event callback to use.
Bake Integration
If you load the plugin using 'bootstrap' => true, this plugin can be used to autodetect usage via the properly named database table. To do so, simply create a table with the version schema above named after the table you'd like to revision plus the suffix _versions. For instance, to version the following table:
CREATE TABLE `posts` (
`id` int(11) unsigned NOT NULL AUTO_INCREMENT,
`category_id` int(11) DEFAULT NULL,
`user_id` int(11) DEFAULT NULL,
`status` varchar(255) NOT NULL DEFAULT 'published',
`visibility` varchar(255) NOT NULL DEFAULT 'public',
`title` varchar(255) NOT NULL DEFAULT '',
`route` varchar(255) DEFAULT NULL,
`content` text,
`published_date` datetime DEFAULT NULL,
`created` datetime NOT NULL,
`modified` datetime NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
Create the following table:
CREATE TABLE `posts_versions` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`version_id` int(11) NOT NULL,
`model` varchar(255) NOT NULL,
`foreign_key` int(11) NOT NULL,
`field` varchar(255) NOT NULL,
`content` text,
`created` datetime NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
You can create a migration for this with the following bake command:
bin/cake bake migration create_posts_versions version_id:integer model foreign_key:integer field content:text created
You'll also want to set the
contentfield in this migration to nullable, otherwise you won't be able to version fields that can be nulled.
To track the current version in the posts table, you can create a migration to add the version_id field to the table:
bin/cake bake migration add_version_id_to_posts version_id:integer
Configuration
There are five behavior configurations that may be used:
versionTable: (Default:version) The name of the table to be used to store versioned data. It may be useful to use a different table when versioning multiple types of entities.versionField: (Default:version_id) The name of the field in the versioned table that will store the current version. If missing, the plugin will continue to work as normal.additionalVersionFields: (Default['created']) The additional or custom fields of the versioned table to be exposed as well. By default prefixed withversion_, e.g.'version_user_id'for'user_id'.referenceName: (Default: db table name) Discriminator used to identify records in the version table.onlyDirty: (Default: false) Set to true to version only dirty properties.
![[RFC] Added typing support](https://avatars.githubusercontent.com/u/184903?v=4)
23 Dec 27, 2020
41 Jul 29, 2022
88 Nov 14, 2022
49 Jun 22, 2022
129 Apr 1, 2022
92 Nov 23, 2022
6 Dec 17, 2021
88 Nov 5, 2022
49 Jan 4, 2023
2 May 12, 2022
2 Jul 25, 2022
7 Nov 3, 2022
1 Apr 8, 2022
2 Jan 7, 2022
745 Jan 7, 2023
2.3k Dec 30, 2022
1 Jan 6, 2022
12 Dec 11, 2022
7 Nov 22, 2022
50 Jul 30, 2022