README

Automatic audit trail for Yii2 ActiveRecord models.

Attach a single behavior to any ActiveRecord model and every change is logged to a database table:

Each log entry also records who (user ID), when (timestamp) and from where (client IP).

Documentación en español: README.es.md

Features

• One-line setup: declare the behavior and the model is audited.
• Excluded attributes: invisible to the log — never stored, and changes to them alone don't create a log entry.
• Masked attributes: the log records that the attribute was set or changed, but its value is always replaced with ***** (ideal for passwords, tokens and other secrets).
• Configurable log table: different models can log to different tables.
• Logging failures never break the operation being logged.
• Works in web and console applications.
• Database agnostic: PostgreSQL, MySQL/MariaDB and SQLite covered by tests.

Requirements

• PHP >= 8.0
• Yii2 >= 2.0.45
• For native JSON columns: PostgreSQL 9.4+, MySQL 5.7+ or MariaDB 10.2+. On other databases (e.g. SQLite) the JSON payload is stored in a text column transparently.

Installation

composer require juliofarra/yii2-logevent

Migration

The package ships a namespaced migration that creates the log_event table. Add the namespace to your console configuration:

// console/config/main.php (or config/console.php)
'controllerMap' => [
    'migrate' => [
        'class' => 'yii\console\controllers\MigrateController',
        'migrationNamespaces' => [
            'console\migrations',           // your own migrations
            'lab37\logevent\migrations',    // yii2-logevent
        ],
    ],
],

Then run:

php yii migrate

The table created is:

Usage

Declare the behavior in any ActiveRecord model:

use lab37\logevent\LogEventBehavior;

class Order extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'logEvent' => [
                'class' => LogEventBehavior::class,
            ],
        ];
    }
}

That's it. Every insert, update and delete on Order is now logged.

Excluding and masking attributes

'logEvent' => [
    'class'   => LogEventBehavior::class,
    'exclude' => ['internal_token'],   // invisible to the log
    'mask'    => ['password'],         // logged, but value hidden
],

• exclude — the attribute never appears in the logged JSON. If an update only changes excluded attributes, no log entry is created at all.
• mask — the attribute appears in the logged JSON, so you know it was set or changed, but its value is always ***** (configurable via maskValue). A null masked value is kept as null, so the log still shows whether the field was loaded.

Example of a logged UPDATE with a masked password:

{
    "status":   {"old": "draft", "new": "sent"},
    "password": {"old": "*****", "new": "*****"}
}

Behavior reference

Logging different models to different tables

Create a subclass of LogEvent that points to another table (create that table with the same structure first):

use lab37\logevent\models\LogEvent;

class OrderLogEvent extends LogEvent
{
    public static function tableName()
    {
        return '{{%order_log_event}}';
    }
}

And configure it in the behavior:

'logEvent' => [
    'class'         => LogEventBehavior::class,
    'logEventClass' => OrderLogEvent::class,
],

Querying the log

The behavior adds a logEvents relation to the owner model (newest first):

foreach ($order->logEvents as $log) {
    echo $log->event;         // INSERT | UPDATE | DELETE
    echo $log->created_at;    // timestamp
    print_r($log->dataArray); // payload decoded as PHP array, on any DB
}

Or query directly:

use lab37\logevent\models\LogEvent;

$logs = LogEvent::find()
    ->forEntity(Order::tableName(), $order->id)
    ->ofEvent(LogEvent::EVENT_UPDATE)
    ->ordered()
    ->all();

Tests

composer install
composer test

The suite runs against an in-memory SQLite database and also exercises the package migration.

License

MIT. See LICENSE.