Download the PHP package josegonzalez/cakephp-version without Composer

Version

A CakePHP 4.x plugin that facilitates versioned database entities

Installation

Add the following lines to your application's composer.json:

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:

Usage

Run the following schema migration:

Note that the content field must be nullable if you want to be able to version any nullable fields in your application.

You may optionally add a version_id field of type integer to 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:

Add the following line to your entities:

And then include the trait in the entity class:

Attach the behavior in the models you want with:

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:

You can optionally retrieve all the 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:

Then define an event listener to handle the event and pass in additional metadata, for example:

Your event listener can then be attached in your project, for example:

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:

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 the following table:

You can create a migration for this with the following bake command:

You'll also want to set the content field 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:

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 with version_, 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.