Eloquent model history tracking for Laravel

2.0.0 2020-05-22 06:49 UTC

This package is auto-updated.

Last update: 2020-05-22 07:04:59 UTC


Test Status Test Status Coverage Status Total Downloads Latest Stable Version License


Eloquent model history tracking for Laravel (NOW WITH AUTOLOAD!)



Laravel 6.x, 7.x

composer require panoscape/history

Laravel 5.6.x

composer require "panoscape/history:^1.0"

Service provider and alias

Only required for version 1.x

NO NEED for version 2.0+ which is auto-loaded with Package Discovery


'providers' => [
'aliases' => [
    'App\History' => Panoscape\History\History::class,


php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=migrations


php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=config


php artisan vendor:publish --provider="Panoscape\History\HistoryServiceProvider" --tag=translations


Add HasOperations trait to user model.


namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Database\Eloquent\SoftDeletes;
use Panoscape\History\HasOperations;

class User extends Authenticatable
    use Notifiable, SoftDeletes, HasOperations;

Add HasHistories trait to the model that will be tracked.


namespace App;

use Illuminate\Database\Eloquent\Model;
use Panoscape\History\HasHistories;

class Article extends Model
    use HasHistories;

    public function getModelLabel()
        return $this->display_name;

Remember that you'll need to implement the abstract getModelLabel method from the trait. This provides the model instance's name in histories.

Get histories of a model

//or dynamic property

Get operations of a user

//or dynamic property

Additional query conditions

Both histories and operations return Eloquent relationships which also serve as query builders. You can add further constraints by chaining conditions:

// get the lastest 10 records
$model->histories()->orderBy('performed_at', 'desc')->take(10)

// filter by user id
$model->histories()->where('user_id', 10010)


//get the associated model

//get the associated user
//the user is the authorized user when the action is being performed
//it might be null if the history is performed unauthenticatedly
//check user existence

//get the message

//get the meta(only available when it's an updating operation)
//the meta will be an array with the properties changing information

//get the timestamp the action was performed at

A sample message

Created Project my_project

A sample meta

    ['key' => 'name', 'old' => 'myName', 'new' => 'myNewName'],
    ['key' => 'age', 'old' => 10, 'new' => 100],

Custom History

Besides the built in created/updating/deleting/restoring events, you may store custom history record with ModelChanged event.

use Panoscape\History\Events\ModelChanged;

//fire a model changed event
event(new ModelChanged($user, 'User roles updated', $user->roles()->pluck('id')->toArray()));

The ModelChanged constructor accepts two/three arguments. The first is the associated model instance; the second is the message; the third is optional, which is the meta(array);


You may localize the model's type name.

To do that, add the language line to the models array in the published language file, with the key being the class's base name in snake case.


//you may added your own model name language line here
    'models' => [
        'project' => '项目',
        'component_template' => '组件模板',

This will translate your model history into

创建 项目 project_001


You may set whitelist and blacklist in config file. Please follow the description guide in the published config file.

Known issues

  1. When updating a model, if its model label(attributes returned from getModelLabel) has been modified, the history message will use its new attributes, which might not be what you expect.
class Article extends Model
    use HasHistories;

    public function getModelLabel()
        return $this->title;
// original title is 'my title'
// modify title
$article->title = 'new title';
// the updating history message
// expect: Updating Article my title
// actual: Updating Article new title

A workaround

public function getModelLabel()
    return $this->getOriginal('title', $this->title);