ModelScribe Quickstart: Audit Your First Eloquent Model

By the end of this page you will have a working audit log: an Eloquent model wired up to ModelScribe, a set of create, update, and delete operations that produce log entries, and a query that retrieves those entries so you can inspect exactly what was recorded. All that’s needed is a completed installation.

ModelScribe automatically resolves Auth::user() as the causer for every log entry created during an authenticated request. No extra configuration is required — the authenticated user is captured and stored as a polymorphic causer relationship on each entry.

Step-by-Step Walkthrough

Add HasAuditLog to a model

Import the HasAuditLog trait and add it to any Eloquent model. That single line is all the setup required — ModelScribe will automatically observe created, updated, and deleted events from this point on.

<?php

namespace App\Models;

use HypathBel\ModelScribe\Traits\HasAuditLog;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasAuditLog;
}

Trigger audited Eloquent operations

Perform ordinary Eloquent operations on your model — ModelScribe intercepts the lifecycle events and writes a log entry for each one automatically.

<?php

use App\Models\Product;

// Creates a log entry with event = 'created'
$product = Product::create([
    'name'  => 'Wireless Keyboard',
    'price' => 49.99,
    'stock' => 100,
]);

// Creates a log entry with event = 'updated',
// capturing old and new values for changed attributes
$product->update([
    'price' => 44.99,
    'stock' => 95,
]);

// Creates a log entry with event = 'deleted'
$product->delete();

Query the log entries

Retrieve the audit trail for your model using the ScribeLog model’s forSubject() scope. This returns a standard Eloquent query builder, so you can chain any additional constraints or ordering you need.

<?php

use HypathBel\ModelScribe\Models\ScribeLog;

$logs = ScribeLog::forSubject($product)->latest()->get();

foreach ($logs as $entry) {
    echo $entry->event;           // 'created', 'updated', 'deleted'
    echo $entry->log_name;        // 'default' (or your custom store name)
    echo $entry->causer_type;     // e.g. 'App\Models\User'
    echo $entry->causer_id;       // e.g. 42
    echo $entry->ip_address;      // e.g. '203.0.113.5'
    echo $entry->url;             // e.g. 'https://example.com/products'
}

Inspect a log record

A typical log entry for an updated event looks like this. The properties column holds an old snapshot of the values before the change and an attributes snapshot of the values after — giving you a complete, reversible diff.

// $entry (ScribeLog model instance) — example for an 'updated' event
[
    'id'           => 2,
    'log_name'     => 'default',
    'event'        => 'updated',
    'description'  => null,
    'subject_type' => 'App\\Models\\Product',
    'subject_id'   => 1,
    'causer_type'  => 'App\\Models\\User',
    'causer_id'    => 42,
    'properties'   => [
        'old'        => ['price' => 49.99, 'stock' => 100],
        'attributes' => ['price' => 44.99, 'stock' => 95],
    ],
    'url'          => 'https://example.com/products/1',
    'ip_address'   => '203.0.113.5',
    'user_agent'   => 'Mozilla/5.0 ...',
    'batch_uuid'   => null,
    'tags'         => [],
    'created_at'   => '2025-07-14T10:22:00.000000Z',
    'updated_at'   => '2025-07-14T10:22:00.000000Z',
]

Customising Audit Behaviour Per Model

Once you have the basics working, you can tailor what ModelScribe records on a model-by-model basis using five optional properties on the model class. All properties are optional — omit any you don’t need and the package default applies.

<?php

namespace App\Models;

use HypathBel\ModelScribe\Traits\HasAuditLog;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use HasAuditLog;

    // Only capture these lifecycle events (default: ['created', 'updated', 'deleted'])
    protected array $auditEvents = ['created', 'updated'];

    // Limit which attributes are recorded per event.
    // Omit an event key (or set it to '*') to capture all attributes for that event.
    protected array $auditAttributes = [
        'created' => ['status', 'total_price', 'customer_id'],
        'updated' => ['status', 'total_price', 'shipping_address'],
    ];

    // Route this model's entries to a named store defined in config/model-scribe.php.
    // Maps to the `log_name` column and selects the correct DB table for the store.
    protected string $auditLogName = 'orders';

    // Attach these tags to every log entry from this model for easy filtering.
    protected array $auditTags = ['warehouse-A', 'priority-high'];

    // Override the application-wide default driver just for this model.
    // null = use the global default from config/model-scribe.php.
    protected ?string $auditDriver = null;
}

Need to record an action that isn’t tied to an Eloquent model — such as a bulk CSV import, a user login event, or a background job completing? Use the ModelScribe facade to write directly to any driver. See the Manual Logging guide for full details.

Getting Started

Core Concepts

Usage

Configuration

Maintenance

ModelScribe Quickstart: Audit Your First Eloquent Model

Step-by-Step Walkthrough

Customising Audit Behaviour Per Model

​Step-by-Step Walkthrough

​Customising Audit Behaviour Per Model

Step-by-Step Walkthrough

Customising Audit Behaviour Per Model