README

This package keeps track of every attribute that changes on an Eloquent model by storing one log row per attribute plus metadata about the acting model. It includes helpers to filter logs by attribute, subject, date, and causer so you can answer questions such as “when was status last changed on this model?” or “which models had stage updated yesterday?”

Features

Automatically listen to the created/updated events (customizable via $recordEvents)
Persist each mutated attribute as a separate log entry with its subject, causer, attribute, and resolved value
Support relation attributes and JSON-path segments (e.g. order.customer.name, payload->meta.inner)
Expose fluent scopes for filtering by attribute, causer, date ranges, and subjects

Installation

You can install the package via composer:

composer require dvsoftsrl/laravel-attributechangelog

You can publish and run the migrations with:

php artisan vendor:publish --provider="DvSoft\AttributeChangeLog\AttributeChangeLogServiceProvider" --tag="attributechangelog-migrations"

Note: The default migration assumes you are using integers for your model IDs. If you are using UUIDs, or some other format, adjust the format of the subject_id and causer_id fields in the published migration before continuing.

After publishing the migration you can create the activity_log table by running the migrations:

php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="DvSoft\AttributeChangeLog\AttributeChangeLogServiceProvider" --tag="attributechangelog-config"

This is the contents of the published config file:

return [
    'enabled' => env('ATTRIBUTE_CHANGE_LOGGER_ENABLED', true),
    'attribute_change_log_model' => \DvSoft\AttributeChangeLog\Models\AttributeChangeLog::class,
    'table_name' => env('ATTRIBUTE_CHANGE_TABLE_NAME', 'activity_log'),
    'database_connection' => env('ATTRIBUTE_CHANGE_DB_CONNECTION'),
];

You can override the log model (must implement DvSoft\AttributeChangeLog\Contracts\AttributeChangeLog) or change the table/connection before running the migrations.

Usage

use DvSoft\AttributeChangeLog\Traits\LogsAttributeChange;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model
{
    use LogsAttributeChange;

    protected $fillable = ['name', 'status'];
}

The trait listens for the configured events, writes one AttributeChangeLog row per attribute, and records the current value, root subject, optional JSON path, and optional causer. You can customize which attributes should be watched by overriding $attributesToBeLogged. When you record objects (for example, DTOs returned by custom casts) the log now keeps the original class plus a serialized payload so reading the entry returns the same object instance it stored.

$myModel = MyModel::find(1);
$myModel->status = 'published';
$myModel->save();

$lastStatusChange = $myModel->attributeChangeLogs()
    ->forAttribute('status')
    ->latest('created_at')
    ->first();

$yesterdayLogs = MyModel::editedAttributeOn('status', today()->subDay())->get();

Models that need to act as causers can use DvSoft\AttributeChangeLog\Traits\CausesActivity to expose the inverse morph relationship.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

dvsoftsrl / laravel-attributechangelog

Maintainers

Details