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.

ScribeEvent is a PHP 8.1+ backed string enum in HypathBel\ModelScribe\Enums that represents the type of audit event recorded by ModelScribe. Every log entry — whether written automatically by the observer or manually via the facade — carries one of these six event types. Being a backed enum, each case has a string value that is stored in the event column of the audit table and can round-trip cleanly between PHP and the database. 
use HypathBel\ModelScribe\Enums\ScribeEvent;

​
Enum Definition

enum ScribeEvent: string
{
    case Retrieved = 'retrieved';
    case Created   = 'created';
    case Updated   = 'updated';
    case Deleted   = 'deleted';
    case Restored  = 'restored';
    case Custom    = 'custom';
}

​
Cases

​
ScribeEvent::Retrieved
'retrieved'
Triggered by the Eloquent retrieved event, which fires every time an existing model is fetched from the database. This case is not included in the default $auditEvents array on HasAuditLog.Use it deliberately and sparingly — see the tip at the bottom of this page.
​
ScribeEvent::Created
'created'
Triggered when a new model record is inserted into the database. This is one of the three default events in $auditEvents. The properties.attributes snapshot contains the full set of attributes written at creation time.
​
ScribeEvent::Updated
'updated'
Triggered when an existing model record is saved with changed attributes. This is one of the three default events in $auditEvents. The properties payload contains both old (values before the save) and attributes (values after the save), making it straightforward to compute a diff.
​
ScribeEvent::Deleted
'deleted'
Triggered when a model record is removed from the database (or soft-deleted when the model uses SoftDeletes). This is one of the three default events in $auditEvents. The properties.old snapshot captures the attribute state immediately before deletion.
​
ScribeEvent::Restored
'restored'
Triggered when a soft-deleted model is restored via $model->restore(). Not included in the default $auditEvents array — add 'restored' to the array explicitly on any model that uses SoftDeletes and requires restore tracking.
protected array $auditEvents = ['created', 'updated', 'deleted', 'restored'];
​
ScribeEvent::Custom
'custom'
A free-form event type for manual logging via ModelScribe::log(). Use this for application-level events that have no Eloquent lifecycle equivalent — logins, exports, batch jobs, permission grants, and so on. ScribeEvent::Custom is only ever written by explicit calls to the facade; the observer never emits it automatically.

​
Quick-Reference Table

CaseString valueEmitted by observerDefault in $auditEvents
Retrieved'retrieved'Yes (if enabled)No
Created'created'YesYes
Updated'updated'YesYes
Deleted'deleted'YesYes
Restored'restored'Yes (if enabled)No
Custom'custom'NoNo

​
Usage with the Facade

Both the enum case and its raw string value are accepted by ModelScribe::log(). 
use HypathBel\ModelScribe\Facades\ModelScribe;
use HypathBel\ModelScribe\Enums\ScribeEvent;

// Using the enum case (recommended — type-safe)
ModelScribe::log(
    event:       ScribeEvent::Custom,
    logName:     'system',
    description: 'Scheduled job ran',
);

// Using the string value (equivalent)
ModelScribe::log(
    event:       'custom',
    logName:     'system',
    description: 'Scheduled job ran',
);

​
Filtering query results by event

Because the string value is stored verbatim in the event column, you can use both forms when querying ScribeLog: 
use HypathBel\ModelScribe\Models\ScribeLog;
use HypathBel\ModelScribe\Enums\ScribeEvent;

// Using the scope (accepts a string)
$updates = ScribeLog::forEvent(ScribeEvent::Updated->value)->get();

// Equivalent using a plain string
$updates = ScribeLog::forEvent('updated')->get();
ScribeEvent::from(string $value) is used internally by ModelScribe::log() when you pass a raw string as the $event argument. If the string does not match any enum case, PHP throws a \ValueError. Always use a recognised value — or pass the enum case directly — to avoid this.
// Throws \ValueError: "typo" is not a valid backing value for enum ScribeEvent
ModelScribe::log(event: 'typo', logName: 'system');
ScribeEvent::Retrieved fires on every single model read that hits the database. Adding 'retrieved' to $auditEvents on a heavily-queried model can generate enormous log volume in production — hundreds of entries per page request. Only enable it for models where read tracking is a genuine audit requirement, and consider routing those entries to a high-throughput driver (such as a queue-backed webhook) rather than a synchronous database insert.

Build docs developers (and LLMs) love

Get started for freeTalk to us