Skip to main content

Audit Eloquent Models Automatically

Record created, updated, and deleted events for any Eloquent model without adding Chronicle::record() calls everywhere.

1. Add the trait​

use Chronicle\Eloquent\HasChronicle;

class Order extends Model
{
    use HasChronicle;
}

Chronicle now records order.created, order.updated (with diff), and order.deleted automatically. The actor defaults to Auth::user() ?? 'system'.

2. Restrict or customise (optional)​

class Order extends Model
{
    use HasChronicle;

    // Record only create and delete — skip update noise
    protected array $chronicleEvents = ['created', 'deleted'];

    // Exclude these fields from update diffs
    protected array $chronicleIgnore = ['last_synced_at'];

    // Override the action prefix (default: snake_case class name)
    protected function chronicleActionPrefix(): string
    {
        return 'shop.order';
    }

    // Override the actor
    protected function chronicleActor(): mixed
    {
        return $this->assignedAgent ?? Auth::user() ?? 'system';
    }
}

3. Audit a third-party model​

For models you cannot modify, register an observer in a service provider:

use Chronicle\Facades\Chronicle;

// Default observer — works for most cases
Chronicle::observe(Invoice::class);

// Custom observer for fine-grained control
Chronicle::observe(Invoice::class, InvoiceObserver::class);

Verify it worked​

php artisan tinker
>>> $order = Order::create(['status' => 'pending', ...]);
>>> \Chronicle\Entry\Entry::query()->action('order.created')->count();
// 1

Or in a test:

$chronicle = Chronicle::fake();
Order::create(['status' => 'pending']);
$chronicle->assertRecorded(fn ($e) => $e['action'] === 'order.created');

See also​