Eloquent observers handle the vast majority of audit logging automatically, but some actions worth recording are not tied to a single model’s lifecycle — bulk data exports, user authentication events, background job completions, or multi-step workflows that span several models at once. For these cases, ModelScribe exposes aDocumentation 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.
log() method on the ModelScribe facade (and the underlying class) that lets you record an arbitrary audit entry with full control over every field.
The log() Method Signature
Parameters
The event to record. Accepts either a
ScribeEvent enum case or a raw string value (e.g. 'custom', 'created'). When a string is passed, the class calls ScribeEvent::from($event) internally, so the value must match one of the enum’s defined cases.The routing key stored in the
log_name column. Use this to organise manual entries alongside (or separately from) automatic observer entries. For the database driver this can also control which named table the entry is written to.A human-readable description of the event. This is the main free-text field for capturing intent — for example,
'User initiated a bulk export' or 'Scheduled price recalculation completed'.The Eloquent model that the event is about. Stored as a polymorphic morph pair (
subject_type / subject_id). Pass null when the event does not relate to a single model instance.The Eloquent model that triggered the event — typically the authenticated user. When using the observer, this is resolved automatically via
Auth::user(). For manual logs you must pass it explicitly if you want it recorded.An arbitrary key/value array of additional context to store alongside the entry. For Eloquent observer entries this holds
['old' => [...], 'attributes' => [...]]; for manual entries you can use any structure that suits your use case.An array of string tags attached to the log entry. Useful for cross-cutting concerns such as
'export', 'scheduled', or 'api' that you want to filter on later.Overrides the globally configured default driver for this single call. Pass a named driver key (e.g.
'file') to send this entry to a specific driver regardless of what the application default is set to.Practical Example: Logging a Bulk CSV Export
Passing a plain string for
event is fully supported. For example, event: 'custom' is equivalent to event: ScribeEvent::Custom. Internally the class calls ScribeEvent::from($event), so the string must be a valid enum value ('retrieved', 'created', 'updated', 'deleted', 'restored', or 'custom'). An invalid string will throw a ValueError.Using Dependency Injection
If you prefer to avoid static facade calls — for example to make a service class easier to unit test — you can type-hintHypathBel\ModelScribe\ModelScribe directly in your constructor. Laravel’s service container will resolve it automatically.
ScribeEvent Enum Values
The ScribeEvent enum defines all recognised event types. Use these cases as the event argument for both manual logs and any code that reads from the event column.
| Case | String value | Typical usage |
|---|---|---|
ScribeEvent::Retrieved | 'retrieved' | Model was fetched from the database |
ScribeEvent::Created | 'created' | Model was inserted |
ScribeEvent::Updated | 'updated' | One or more attributes were changed |
ScribeEvent::Deleted | 'deleted' | Model was removed (or soft-deleted) |
ScribeEvent::Restored | 'restored' | Soft-deleted model was restored |
ScribeEvent::Custom | 'custom' | Any event not tied to the Eloquent lifecycle |