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 ModelScribe facade provides a static interface to the underlying HypathBel\ModelScribe\ModelScribe class, which is bound to the Laravel service container. Use it to log arbitrary events outside of Eloquent observers, to trigger driver-level retention pruning, or to access the DriverManager for registering custom drivers. 
// Via the facade (most common)
use HypathBel\ModelScribe\Facades\ModelScribe;

// Via dependency injection (same underlying instance)
use HypathBel\ModelScribe\ModelScribe;

​
Methods

​
log()

Manually record an audit entry without an Eloquent model lifecycle event. Useful for application-level events such as logins, exports, scheduled jobs, or anything that falls outside the standard created / updated / deleted lifecycle. 
ModelScribe::log(
    ScribeEvent|string $event,
    string             $logName     = 'default',
    ?string            $description = null,
    ?Model             $subject     = null,
    ?Model             $causer      = null,
    array              $properties  = [],
    array              $tags        = [],
    ?string            $driver      = null,
): void
​
$event
ScribeEvent|string
required
The event type to record. Accepts a ScribeEvent enum instance (e.g. ScribeEvent::Custom) or its string value (e.g. 'custom'). When a string is passed, ScribeEvent::from() is used internally — passing an unrecognised string will throw a ValueError.
​
$logName
string
default:"'default'"
The routing key written to the log_name column. Use this to group related entries (e.g. 'system', 'orders') and query them later with ScribeLog::inLog().
​
$description
?string
default:"null"
A human-readable sentence describing what happened. Stored in the description column and intended for display in audit UIs or log viewers.
​
$subject
?Model
default:"null"
The Eloquent model that was acted upon (the “what”). Stored as a polymorphic morph pair (subject_type / subject_id) on the log record.
​
$causer
?Model
default:"null"
The actor who triggered the event (the “who”) — typically an App\Models\User. When logging through the Eloquent observer, this defaults to Auth::user(). For manual log() calls, pass the causer explicitly when one exists.
​
$properties
array
default:"[]"
Arbitrary key-value data stored in the properties JSON column. For change-tracking entries, the observer populates ['old' => [...], 'attributes' => [...]]. For custom entries, you may store any structure here.
​
$tags
array
default:"[]"
An array of string tags written to the tags JSON column. Tags enable free-form filtering of entries across log names and event types.
​
$driver
?string
default:"null"
Override which driver handles this specific entry. When null, the globally-configured default driver (from config('model-scribe.default')) is used.

​
prune()

Trigger retention cleanup on a driver, deleting stale records according to its configured retention policy. Returns the number of records removed. 
ModelScribe::prune(?string $driver = null): int
​
$driver
?string
default:"null"
The driver to prune. Pass a named driver key (e.g. 'database') to target a specific driver, or leave as null to prune the global default driver. Drivers that do not manage persistent storage (such as webhook drivers) return 0.

​
getDriverManager()

Return the underlying DriverManager instance. Use this to register custom third-party drivers via extend(), or to flush the resolved driver cache during testing. 
ModelScribe::getDriverManager(): DriverManager

​
Usage Examples

​
Logging a manual event

use HypathBel\ModelScribe\Facades\ModelScribe;
use HypathBel\ModelScribe\Enums\ScribeEvent;

// Log a custom application event with a subject and causer
ModelScribe::log(
    event:       ScribeEvent::Custom,
    logName:     'system',
    description: 'User exported invoice report',
    subject:     $invoice,
    causer:      $request->user(),
    properties:  ['format' => 'pdf', 'rows' => 142],
    tags:        ['export', 'billing'],
);

​
Logging with a string event value

// String values are equivalent to their enum counterparts
ModelScribe::log(
    event:       'custom',
    logName:     'auth',
    description: 'Successful login via SSO',
    causer:      $user,
    properties:  ['provider' => 'google'],
);

​
Routing to a specific driver

// Send a one-off entry to the 'file' driver regardless of the global default
ModelScribe::log(
    event:   ScribeEvent::Custom,
    logName: 'debug',
    driver:  'file',
);

​
Pruning stale records

// Prune the default driver and report how many records were removed
$deleted = ModelScribe::prune();
\Log::info("Pruned {$deleted} stale audit records.");

// Prune a specific named driver
$deleted = ModelScribe::prune('database');

​
Registering a custom driver

use HypathBel\ModelScribe\Facades\ModelScribe;
use App\Audit\WebhookDriver;

// Typically done inside a ServiceProvider's boot() method
ModelScribe::getDriverManager()->extend(
    'webhook',
    function (array $config, \HypathBel\ModelScribe\DriverManager $manager): \HypathBel\ModelScribe\Contracts\DriverInterface {
        return new WebhookDriver($config);
    }
);
The log() method constructs an immutable LogEntry DTO internally and passes it to the resolved driver. The $causer you supply is stored as-is — unlike the observer, ModelScribe::log() does not automatically fall back to Auth::user(). Always pass an explicit causer when one is available.
Call ModelScribe::prune() from a scheduled Artisan command or the package’s built-in model-scribe:prune command on a regular cadence to keep your audit table lean. Wire it up in routes/console.php:
Schedule::command('model-scribe:prune')->daily();

Build docs developers (and LLMs) love

Get started for freeTalk to us