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.

HasAuditLog is a PHP trait in the HypathBel\ModelScribe\Traits namespace. Add it to any Eloquent model to enable automatic audit logging. Once mixed in, the trait registers ModelScribeObserver during model booting and exposes a set of configurable properties that control which events, attributes, driver, and tags are used for that model’s audit entries. 
use HypathBel\ModelScribe\Traits\HasAuditLog;

​
Properties

Override any of the following protected properties on your model to customise how audit logging behaves for that class.
​
$auditEvents
array
default:"['created', 'updated', 'deleted']"
The Eloquent events that ModelScribe will capture for this model. Valid values are 'created', 'updated', 'deleted', and 'restored'. The 'retrieved' event is recognised by the ScribeEvent enum but is not included here by default due to the volume it can produce.
protected array $auditEvents = ['created', 'updated', 'deleted'];
​
$auditAttributes
array
default:"[]"
Per-event attribute allowlists that restrict which model attributes are captured in a log entry. When this property is empty (the default), all changed attributes are recorded.The value can take two forms:
  • Per-event map — keys are event names, values are string arrays or '*' (capture all).
  • Flat array — numeric keys; the same list is applied to every event.
// Per-event map
protected array $auditAttributes = [
    'created' => ['amount', 'status', 'user_id'],
    'updated' => ['amount', 'status'],
    'deleted' => '*', // capture all on delete
];

// Flat list — applied to all events
protected array $auditAttributes = ['amount', 'status'];
​
$auditDriver
?string
default:"null"
Override the globally-configured default driver for this model. When null, the package default (defined in config('model-scribe.default')) is used. Set to a named driver key to route this model’s logs elsewhere.
protected ?string $auditDriver = 'file';
​
$auditLogName
string
default:"'default'"
A routing key stored in the log_name column of every entry produced by this model. Use this to segment logs by domain area (e.g. 'invoices', 'orders') and filter them with the ScribeLog::inLog() scope.
protected string $auditLogName = 'invoices';
​
$auditTags
array
default:"[]"
String tags attached to every log entry created from this model. Tags are stored in the tags JSON column and can be used for free-form filtering downstream.
protected array $auditTags = ['billing', 'finance'];

​
Methods

​
Boot

​
bootHasAuditLog(): void
static void
Static boot method called automatically by Laravel’s model booting mechanism. It registers ModelScribeObserver as an Eloquent observer on the model class via static::observe(ModelScribeObserver::class). You do not need to call this method yourself.

​
Accessors

These methods are called by ModelScribeObserver at runtime to read the model’s audit configuration. You can also call them directly if you need to inspect a model’s audit settings programmatically.
​
getAuditEvents(): array
array
Returns the value of $auditEvents — the list of Eloquent event names that will trigger an audit log entry for this model.
​
getAuditDriver(): ?string
?string
Returns the value of $auditDriver. A null return signals the observer to fall back to the package’s globally-configured default driver.
​
getAuditLogName(): string
string
Returns the value of $auditLogName, which is written to the log_name column of every audit entry produced by this model.
​
getAuditTags(): array
array
Returns the value of $auditTags — the string tags merged into every log entry produced by this model.
​
getAuditableAttributes(string $event): ?array
?array
Returns the attribute allowlist for the given event name, or null if all attributes should be captured.Resolution logic:
  1. If $auditAttributes is empty → return null (capture everything).
  2. If $auditAttributes is a flat array (numeric key at index 0) → return it as-is for every event.
  3. Otherwise, look up $auditAttributes[$event]. If the value is '*' or the key is absent → return null. Otherwise cast to array and return.
$auditAttributes valueReturn for a given event
[]null
['amount', 'status'] (flat)['amount', 'status']
['updated' => ['amount']], event 'updated'['amount']
['updated' => ['amount']], event 'created'null
['updated' => '*']null

​
Full Usage Example

<?php

namespace App\Models;

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

class Invoice extends Model
{
    use SoftDeletes, HasAuditLog;

    // Capture creation, updates, soft-deletes, and restores
    protected array $auditEvents = ['created', 'updated', 'deleted', 'restored'];

    // Only record these attributes on each event type
    protected array $auditAttributes = [
        'created' => ['amount', 'currency', 'status', 'user_id'],
        'updated' => ['amount', 'status'],
        'deleted' => '*',   // snapshot everything on deletion
        'restored' => '*',
    ];

    // Send this model's logs to the 'file' driver instead of the global default
    protected ?string $auditDriver = 'file';

    // Group all entries under the 'invoices' log name
    protected string $auditLogName = 'invoices';

    // Tag every entry for easy downstream filtering
    protected array $auditTags = ['billing', 'finance'];
}
The bootHasAuditLog() method is invoked automatically by Laravel — you never need to call Invoice::bootHasAuditLog() yourself. Laravel discovers all boot{TraitName}() methods on a model and calls them during Model::boot().
When $auditAttributes is a flat (numerically-keyed) array, that allowlist applies to all events. Switch to a per-event map only when you need different attribute sets per event — it keeps your intent explicit and avoids accidentally over-capturing on deletion or creation.

Build docs developers (and LLMs) love

Get started for freeTalk to us