README

Keep a record of changes to models in your application. If a user changes the name of a product from A to B, that change will be stored in a Change model and stored in your database. Only the changed attributes are stored. You can then use this to retrieve the model's history, including which user made the change.

Installation

Step 1: Install with Composer

composer require audunru/model-history

Step 2: Publish and run migrations

Note: Changes are stored in a table called history. You can change this in the configuration, but you will have to publish the configuration before publishing and running the migrations.

php artisan vendor:publish --tag=model-history-migrations
php artisan migrate

Step 3: Add traits to your models

Add the MakesChanges trait to your User model:

namespace App\Models;

use audunru\ModelHistory\Traits\MakesChanges;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use MakesChanges;

Add the HasHistory trait to any model where you want to track changes:

namespace App\Models;

use audunru\ModelHistory\Traits\HasHistory;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasHistory;

Step 4: Retrieve model changes

Assuming that you've added the HasHistory trait to a model named Product, you can retrieve the changes like this:

$product = Product::create([
    'description' => 'Old description',
]);

$product->update([
    'description' => 'New description',
]);

dump($product->changes);

Step 5: Return history as JSON (optional)

The package includes a History API resource for Change models:

use audunru\ModelHistory\Resources\History;

return History::collection($product->history);

Each item contains id, changes, owner (id, name and email of the user who made the change), created_at and updated_at.

Note that the resource shows the email address of each user who changed the model. If you give the history to other users, for example to everyone who can see a product, they also see these email addresses. If you do not want this, write your own JsonResource for the Change model and use it instead of History.

Configuration

Publish the configuration file by running:

php artisan vendor:publish --tag=model-history-config

Available options:

    /*
     * Table where the "Change" model will be stored
     */
    'history_table_name' => 'history',
    /*
     * Eager load the change model's owner
     */
    'eager_load_owner' => true,
    /*
     * Eager load the change model's model
     */
    'eager_load_model' => false,
    /*
     * Date format used when returning the Change model as JSON
     */
    'date_format' => 'Y-m-d H:i:s',
    /*
     * Attribute names that are never recorded in history, regardless of each model's own $ignored
     * list. Override in your published config to add or remove entries.
     */
    'default_ignored' => [
        'password',
        'remember_token',
        'api_token',
    ],

Ignoring attributes

Changes to the attributes in the default_ignored configuration option are never recorded. The created_at and updated_at attributes are also ignored.

To ignore more attributes on a model, use addIgnored():

$product->addIgnored(['gross_cost', 'tax_rate']);

Attributes with an encrypted cast (encrypted, encrypted:array, encrypted:collection, encrypted:json, encrypted:object, AsEncryptedArrayObject and AsEncryptedCollection) are never recorded. If they were, the history table would contain the decrypted value.

Attributes in the model's $hidden array are not recorded either. The changes are serialised before they are stored, and serialisation removes hidden attributes. If only hidden attributes change, the history still gets an entry with the user who made the change, but with no attributes in original and updated.

Development

Testing

Run tests:

composer test

audunru / model-history

Package info

Security

Statistics