Skip to main content

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.

The HasAuditLog trait is the primary way to enable automatic audit logging on any Eloquent model. Adding the trait registers a ModelScribeObserver on the model’s boot cycle, which listens for Eloquent lifecycle events and dispatches a LogEntry to the configured driver. No further configuration is required to get started — the trait’s defaults will capture created, updated, and deleted events for all attributes using whatever driver is set as the global default.

​
Minimal Setup

The simplest way to enable auditing is to add the trait with no additional properties. This captures all three default events across every attribute and routes entries to the default log using the globally configured driver. 
use HypathBel\ModelScribe\Traits\HasAuditLog;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use HasAuditLog;
}

​
Full Customisation

Every aspect of the trait’s behaviour can be overridden by declaring one or more of the five configurable properties on your model. The example below shows all five properties together with inline explanations. 
use HypathBel\ModelScribe\Traits\HasAuditLog;
use Illuminate\Database\Eloquent\Model;

class Invoice extends Model
{
    use HasAuditLog;

    // Only log created and updated events (not deleted)
    protected array $auditEvents = ['created', 'updated'];

    // Per-event attribute allowlist
    protected array $auditAttributes = [
        'created' => ['amount', 'status', 'user_id'],
        'updated' => ['amount', 'status'],
    ];

    // Use the file driver for this model only
    protected ?string $auditDriver = 'file';

    // Route to the 'invoices' named store/table
    protected string $auditLogName = 'invoices';

    // Attach these tags to every log entry
    protected array $auditTags = ['billing', 'finance'];
}

​
Configurable Properties

​
$auditEvents
array
default:"['created', 'updated', 'deleted']"
The list of Eloquent event names to listen for. Only events present in this array will produce a log entry. Valid values are created, updated, deleted, and restored. Removing an event name silences that lifecycle hook entirely for the model.
​
$auditAttributes
array
default:"[]"
Controls which attributes are captured for each event. The property can be structured in two ways:
  • Per-event map — an associative array keyed by event name, where each value is an array of attribute names. Omitting a key or using '*' as the value captures all attributes for that event.
  • Flat array — a non-associative list of attribute names that applies uniformly to every audited event.
An empty array (the default) captures all attributes for all events.
​
$auditDriver
?string
default:"null"
Overrides the globally configured default driver for this model only. When null, the driver defined in config('model-scribe.default') is used. Set this to a named driver key (e.g. 'file', 'database') to route this model’s entries independently.
​
$auditLogName
string
default:"'default'"
A routing key stored in the log_name column of every log entry produced by this model. For the database driver, this key can also map to a specific table via the guard_stores config. Use distinct log names to logically separate audit records by domain (e.g. 'invoices', 'orders').
​
$auditTags
array
default:"[]"
An array of string tags attached to every LogEntry produced by this model. Tags are stored in the tags column and can be used to filter or categorise log records independently of the event name or log name.
You can pass $auditAttributes as a flat (non-associative) array to apply the same attribute filter across all audited events without repeating yourself. For example, protected array $auditAttributes = ['amount', 'status']; will restrict captured attributes to amount and status on every event the model listens for.

​
Accessor Methods

The observer and any custom extensions interact with the trait through a set of public accessor methods rather than reading the properties directly. These methods are also useful if you extend ModelScribeObserver or build tooling on top of the trait.
​
getAuditEvents(): array
Returns the list of event names the model is configured to audit. Reads directly from $auditEvents.
​
getAuditDriver(): ?string
Returns the model-level driver override, or null if the model defers to the global default.
​
getAuditLogName(): string
Returns the log routing key for this model. Defaults to 'default'.
​
getAuditTags(): array
Returns the tag array to be attached to every log entry from this model.
​
getAuditableAttributes(string $event): ?array
Resolves the attribute allowlist for a specific event name. Returns null when all attributes should be captured (either because $auditAttributes is empty, or the event key maps to '*'). Returns a string array when an explicit allowlist is configured. The observer calls this method on every event to decide which model attributes to include in the LogEntry.

Build docs developers (and LLMs) love

Get started for freeTalk to us