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!
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
revisionsdatabase table. - Revisions are created automatically on model update, using the
updatedEloquent 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
deletedEloquent 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
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
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();
}
}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.
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;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)
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();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);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();
}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);
}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');
}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');
}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();
}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');
}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();
}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();
}
}If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see LICENSE for more information.
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.