Download the PHP package zbiller/laravel-revisions without Composer

Package discontinued! Check out VARBOX.IO instead.

Unfortunately this package is now discontinued.
Please check out Varbox (Laravel Admin Panel) for this functionality and much more.

• Buy: https://varbox.io/buy
• Docs: https://varbox.io/docs
• Demo: https://demo.varbox.test/admin
• Repo https://github.com/VarboxInternational/varbox

Thank you!

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):

Install the package via Composer (for Laravel 5.8):

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

Publish the config file with:

Publish the migration file with:

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

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:

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.

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:

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:

Rollback to a past revision

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

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.

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.

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.

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.

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.

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).

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.

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.

Credits

• Andrei Badea
• All Contributors

Security

If you discover any security related issues, please email [email protected] 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.