Download the PHP package convenia/revisionable without Composer

Easily create a revision history for any Eloquent model

And you're good to go!

This project is a fork of https://github.com/VentureCraft/revisionable with some improvements and new features

The v1 readme is also available if you want to use an old 1.x version

Installation

Via composer (recommended)

Next, you must install the service provider:

You can publish the migration with:

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

Docs

• Implementation
  • Soft deletes
  • Creation
• Contributing

Implementation

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.

You can also disable revisioning after X many revisions have been made by setting $historyLimit to the number of revisions you want to keep before stopping revisions.

In order to maintain a limit on history, but instead of stopping tracking revisions if you want to remove old revisions, you can accommodate that feature by setting $revisionCleanup.

You can suspend or set the revision temporarily by calling the methods withourRevision() and withRevision().

However, this doesn't overrides the revisionEnabled variable. If you call the method withRevision() in a Model that has setted $revisionEnabled = false, the revision will not occur.

Divergent column and model names

Sometimes a model can have a relationship in which the column associated doesn't follow the eloquent pattern, being needed to specify the foreign. In these cases, you need to declare an array called divergentRelations, where the column name points to the model name, in lowercase. This makes possible to query the relationship field value (like name or title), when using the methods newValue or oldValue on the revision

If you don't set the array $divergentRelations and tries to get the revision newValue, you would get the id instead of the name or title;

Storing soft deletes

By default, if your model supports soft deletes, revisionable will store this and any restores as updates on the model.

You can choose to ignore deletes and restores by adding deleted_at to your $dontKeepRevisionOf array.

To better format the output for deleted_at entries, you can use the isEmpty formatter (see Format output for an example of this.)

Storing creations

By default the creation of a new model is not stored as a revision. Only subsequent changes to a model is stored.

If you want to store the creation as a revision you can override this behavior by setting revisionCreationsEnabled to true by adding the following to your model:

Format output

You can continue (and are encouraged to) use eloquent accessors in your model to set the output of your values, see the laravel docs for more information on accessors The below documentation is therefor deprecated

In cases where you want to have control over the format of the output of the values, for example a boolean field, you can set them in the $revisionFormattedFields array in your model. e.g.,

You can also override the field name output using the $revisionFormattedFieldNames array in your model, e.g.,

This comes into play when you output the revision field name using $revision->fieldName()

String

To format a string, simply prefix the value with string: and be sure to include %s (this is where the actual value will appear in the formatted response), e.g.,

Boolean

Booleans by default will display as a 0 or a 1, which is pretty bland and won't mean much to the end user, so this formatter can be used to output something a bit nicer. Prefix the value with boolean: and then add your false and true options separated by a pipe, e.g.,

DateTime

DateTime by default will display as Y-m-d H:i:s. Prefix the value with datetime: and then add your datetime format, e.g.,

Is Empty

This piggy backs off boolean, but instead of testing for a true or false value, it checks if the value is either null or an empty string.

This can also accept %s if you'd like to output the value, something like the following will display 'Nothing' if the value is empty, or the actual value if something exists:

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 convenia/revisionable/issues