Create revisions for any Eloquent model along with its relationships

Overview
Installation
Setup
Usage
Customisations
Events

Overview

This package allows you to create revisions for any Eloquent model record along with its underlying relationships.

When a revision is created, it gets stored inside the revisions database table.
Revisions are created automatically on model update, using the updated Eloquent event
Revisions can also can be created manually by using the saveAsRevision()
When a record is force deleted, all its revisions will also be removed automatically, using the deleted Eloquent event

As already mentioned, this package is capable of revisioning entire relationships alongside the model record.

The cool part is that it's also capable of re-creating the relationships records from ground up, if they were force deleted along the way, during the lifetime of that model record.

Relationship types that can be revisioned: hasOne, morphOne, hasMany, morphMany, belongsToMany, morphToMany

Installation

Install the package via Composer (for Laravel 6.0 and above):

composer require neurony/laravel-revisions

Install the package via Composer (for Laravel 5.8):

composer require neurony/laravel-revisions:3.1.0

Install the package via Composer (for Laravel 5.7 and below):

composer require neurony/laravel-revisions:2.0.0

Publish the config file with:

php artisan vendor:publish --provider="Neurony\Revisions\ServiceProvider" --tag="config"

Publish the migration file with:

php artisan vendor:publish --provider="Neurony\Revisions\ServiceProvider" --tag="migrations"

After the migration has been published you can create the revisions table by running:

php artisan migrate

Setup

Step 1

Your Eloquent models should use the Neurony\Revisions\Traits\HasRevisions trait and the Neurony\Revisions\Options\RevisionOptions class.

The trait contains an abstract method getRevisionOptions() that you must implement yourself.

Here's an example of how to implement the trait:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Neurony\Revisions\Options\RevisionOptions;
use Neurony\Revisions\Traits\HasRevisions;

class YourModel extends Model
{
    use HasRevisions;

    /**
     * Get the options for revisioning the model.
     *
     * @return RevisionOptions
     */
    public function getRevisionOptions(): RevisionOptions
    {
        return RevisionOptions::instance();
    }
}

Step 2

Inside the revisions.php config file, write the full namespace of your User model class for the user_model config key.

By default, this value is the FQN of Laravel's User model class (\App\User). You can also leave this NULL if your application doesn't have the concept of users.

This bit is used by the Neurony\Revisions\Traits\HasRevisions trait to know who created which revisions.

Usage

Fetch revisions

You can fetch a model record's revisions by using the revisions() morph to many relation present on the Neurony\Revisions\Traits\HasRevisions trait.

$model = YourModel::find($id);

$revisions = $model->revisions;

Create revisions (automatically)

Once you've used the Neurony\Revisions\Traits\HasRevisions trait in your Eloquent models, each time you update a model record, a revision containing its original attribute values will be created automatically using the updated Eloquent event:

// model is state 1
$model = YourModel::find($id);

// model is state 2
// a revision containing the model's state 1 is created 
$model->update(...);

Alternatively, you can also store a revision each time you create a new model record, by using the created Eloquent event
(see Customisations)

Create revisions (manually)

If you ever need it, you can also create a revision manually, by using the saveAsRevision() method from the Neurony\Revisions\Traits\HasRevisions trait:

$model = YourModel::find($id);

// a new entry is stored inside the 'revisions' database table
// reflecting the current state of that model record
$model->saveAsRevision();

Rollback to a past revision

You can rollback the model record to one of its past revisions by using the rollbackToRevision() method.

// model is state 1
$model = YourModel::find($id);
$revision = $model->revisions()->latest()->first();

// model is now in state 0
$model->rollbackToRevision($revision);

Customisations

Enable revisioning on create

By default, when creating a new model record, a revision will not be created, because the record is fresh and it's at its first state. However, if you wish to create a revision when creating the model record, you can do so by using the enableRevisionOnCreate() method in your definition of the getRevisionOptions() method.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->enableRevisionOnCreate();
}

Limit the revisions

You can limit the number of revisions each model record can have by using the limitRevisionsTo() method in your definition of the getRevisionOptions() method.

This prevents ending up with thousands of revisions for a heavily updated record.

When the limit is reached, after creating the new (latest) revision, the script automatically removes the oldest revision that model record has.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->limitRevisionsTo(100);
}

Revision only certain fields

If you don't want to revision all the model's fields (attributes), you can manually specify which fields you wish to store when creating a new revision, by using the fieldsToRevision() method in your definition of the getRevisionOptions() method.

Please note that the fields omitted won't be stored when creating the revision, but when rolling back to a revision, those ignored fields will become null / empty for the actual model record.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->fieldsToRevision('title', 'content');
}

Exclude certain fields from being revisioned

Opposed to the fieldsToRevision() method, if you want to exclude certain fields when making a revision of an Eloquent model, use the fieldsToNotRevision() method in your definition of the getRevisionOptions() method

Please note that the fieldsToRevision() takes precedence over the fieldsToNotRevision().
Don't use both of these methods in the same definition of the getRevisionOptions method.

Please note that the fields omitted won't be stored when creating the revision, but when rolling back to a revision, those ignored fields will become null / empty for the actual model record.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->fieldsToNotRevision('title', 'content');
}

Include timestamps when creating a revision

By default, when creating a revision, the actual model's timestamps are automatically excluded from the actual revision data.

If you'd like to store the model's timestamps when creating a revision, please use the withTimestamps() method in your definition of the getRevisionOptions() method.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->withTimestamps();
}

Revision relationships alongside the model record

More often than not you will want to create a full copy in time of the model record and this includes revisioning its relations too (especially child relations).

You can specify what relations to be revisioned alongside the model record by using the relationsToRevision() method in your definition of the getRevisionOptions() method.

Please note that when rolling back the model record to a past revision, the specified relations will also be rolled back to their state when that revision happened (this includes re-creating a relation record from ground up if it was force deleted along the way, or deleting any future added related records up until the revision checkpoint).

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->relationsToRevision('comments', 'author');
}

Disable creating a revision when rolling back

By default, when rolling back to a past revision, a new revision is automatically created. This new revision contains the model record's state before the rollback happened.

You can disable this behavior by using the disableRevisioningWhenRollingBack() method in your definition of the getRevisionOptions() method.

/**
 * Get the options for revisioning the model.
 *
 * @return RevisionOptions
 */
public function getRevisionOptions(): RevisionOptions
{
    return RevisionOptions::instance()
        ->disableRevisioningWhenRollingBack();
}

Events

The revision functionality comes packed with two Eloquent events: revisioning and revisioned

You can implement these events in your Eloquent models as you would implement any other Eloquent events that come with the Laravel framework.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Neurony\Revisions\Options\RevisionOptions;
use Neurony\Revisions\Traits\HasRevisions;

class YourModel extends Model
{
    use HasRevisions;

    /**
     * Boot the model.
     *
     * @return RevisionOptions
     */
    public static function boot()
    {
        parent::boot();

        static::revisioning(function ($model) {
            // your logic here
        });

        static::revisioned(function ($model) {
            // your logic here
        });
    }
    
    /**
     * Get the options for revisioning the model.
     *
     * @return RevisionOptions
     */
    public function getRevisionOptions(): RevisionOptions
    {
        return RevisionOptions::instance();
    }
}

Credits

Security

If you discover any security related issues, please email andrei.badea@neurony.ro instead of using the issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

elvendor / laravel-revisions