README

Wouldn't it be nice to have a revision history for any model in your Laravel 4 project, without having to do any hard work for it?

By simply extending Revisionable from your models, you can instantly have just that and be able to display a history similar to this:

Chris changed title from 'Something' to 'Something else'
Chris changed category from 'News' to 'Breaking news'
Matt changed category from 'Breaking news' to 'News'

So not only can you see a history of what happened, but who did what, so there's accountability.

Revisionable is a Laravel 4 package that allows you to keep a revision history for your models without thinking.

For some background and info, see this article

Installation

Revisionable is installable via composer, the details are on packagist, here.

Add the following to the require section of your project's composer.json file:

"maclof/revisionable": "dev-master",

Then run composer update to download the package:

php composer.phar update

Finally, you'll also need to run the package migrations:

php artisan migrate --package=maclof/revisionable

Effortless revision history

For any model that you want to keep a revision history for, include the revisionable namespace and extend revisionable instead of eloquent, e.g.,

use Maclof\Revisionable\Revisionable;

class Article extends Revisionable { }

If needed, you can disable the revisioning by setting $revisionEnabled to false in your model. This can be handy if you want to temporarily disable revisioning, or if you want to create your own base model that extends revisionable, which all of your models extend, but you want to turn revisionable off for certain models.

use Maclof\Revisionable\Revisionable;

class Article extends Revisionable
{
    protected $revisionEnabled = false;
}

More control

No doubt, there'll be cases where you don't want to store a revision history only for certain fields of the model, this is supported in two different ways. In your model you can either specifiy which fields you explicitly want to track and all other fields are ignored:

protected $keepRevisionOf = array(
    'title'
);

Or, you can specify which fields you explicitly don't want to track. All other fields will be tracked.

protected $dontKeepRevisionOf = array(
    'category_id'
);

The $keepRevisionOf setting takes precendence over $dontKeepRevisionOf

Load revision history

To load the revision history for a given model, simply call the revisionHistory method on that model, e.g.,

$article = Article::find($id);
$history = $article->revisionHistory;

Displaying history

For the most part, the revision history will hold enough information to directly output a change history, however in the cases where a foreign key is updated we need to be able to do some mapping and display something nicer than plan_id changed from 3 to 1.

To help with this, there's a few helper methods to display more insightful information, so you can display something like Chris changed plan from bronze to gold.

The above would be the result from this:

@foreach($account->revisionHistory as $history )
    <li>{{ $history->userResponsible()->first_name }} changed {{ $history->fieldName() }} from {{ $history->oldValue() }} to {{ $history->newValue() }}</li>
@endforeach

userResponsible()

Returns the User that was responsible for making the revision. A user model is returned, or null if there was no user recorded.

fieldName()

Returns the name of the field that was updated, if the field that was updated was a foreign key (at this stage, it simply looks to see if the field has the suffix of _id) then the text before _id is returned. e.g., if the field was plan_id, then plan would be returned.

identifiableName()

This is used when the value (old or new) is the id of a foreign key relationship.

By default, it simply returns the ID of the model that was updated. It is up to you to override this method in your own models to return something meaningful. e.g.,

use Maclof\Revisionable\Revisionable;

class Article extends Revisionable
{
    public function identifiableName()
    {
        return $this->title;
    }
}

oldValue() and newValue()

Get the value of the model before or after the update. If it was a foreign key, identifiableName() is called.

Unknown or invalid foreign keys as revisions

In cases where the old or new version of a value is a foreign key that no longer exists, or indeed was null, there are two variables that you can set in your model to control the output in these situations:

protected $revisionNullString = 'nothing';
protected $revisionUnknownString = 'unknown';

disableRevisionField()

Sometimes temporarily disabling a revisionable field can come in handy, if you want to be able to save an update however don't need to keep a record of the changes.

$object->disableRevisionField('title'); // Disables title

or:

$object->disableRevisionField(array('title', 'content')); // Disables title and content

Contributing

Contributions are encouraged and welcome; to keep things organised, all bugs and requests should be opened in the github issues tab for the main project, at maclof/revisionable/issues

maclof / revisionable

Maintainers

Details