Documentation Index
Fetch the complete documentation index at: https://mintlify.com/HypathStack/model-scribe/llms.txt
Use this file to discover all available pages before exploring further.
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.