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.

After running php artisan vendor:publish --tag="model-scribe-config", the file config/model-scribe.php becomes the single source of truth for all ModelScribe behaviour. Every option — from which driver persists your audit records to how long they are kept — is controlled here. The sections below walk through each top-level key and every nested driver block in detail.

​
Default configuration file

<?php

// config for HypathBel/ModelScribe

return [

    /*
    |--------------------------------------------------------------------------
    | Default Driver
    |--------------------------------------------------------------------------
    | Which driver to use by default. Can be overridden per-model via the
    | $auditDriver property on the model using the HasAuditLog trait.
    |
    | Supported: "database", "file", "stack"
    */
    'default' => env('MODEL_SCRIBE_DRIVER', 'database'),

    /*
    |--------------------------------------------------------------------------
    | Drivers
    |--------------------------------------------------------------------------
    | Each driver has its own configuration block. The "stack" driver fans out
    | a single log entry to multiple other drivers simultaneously.
    */
    'drivers' => [

        'database' => [
            'driver' => 'database',

            // Which DB connection to use. null = app default.
            'connection' => env('MODEL_SCRIBE_DB_CONNECTION', null),

            // Default table for models that don't define a specific store.
            'table' => env('MODEL_SCRIBE_TABLE', 'model_scribe_logs'),

            'stores' => [],

            'retention' => [
                // 'permanent' — never delete automatically
                // 'days'      — delete records older than `days`
                // 'rotating'  — keep only the latest `keep` records per table
                'type' => env('MODEL_SCRIBE_RETENTION', 'permanent'),
                'days' => (int) env('MODEL_SCRIBE_RETENTION_DAYS', 90),
                'keep' => (int) env('MODEL_SCRIBE_RETENTION_KEEP', 500),
            ],

            'auth_guard' => null,
        ],

        'file' => [
            'driver' => 'file',

            // Any channel defined in config/logging.php.
            'channel' => env('MODEL_SCRIBE_LOG_CHANNEL', 'daily'),

            'auth_guard' => null,
        ],

        'stack' => [
            'driver' => 'stack',

            // Fan-out to these named drivers.
            'drivers' => ['database', 'file'],

            'auth_guard' => null,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Global Settings
    |--------------------------------------------------------------------------
    */

    // Capture request context (URL, IP, User-Agent) for every log entry.
    'capture_request_context' => true,

    // The guard to use when resolving the authenticated causer.
    // null = auto-detect from Auth::user().
    'auth_guard' => null,

    /*
    |--------------------------------------------------------------------------
    | Guard-based Routing
    |--------------------------------------------------------------------------
    | Map an authentication guard name to a specific store. This is used if
    | the model being audited hasn't defined a specific $auditLogName.
    */
    'guard_stores' => [
        // 'api' => 'invoices',
        // 'web' => 'orders',
    ],

];

​
Top-level keys

​
default
string
required
The name of the driver that ModelScribe uses unless a model overrides it with $auditDriver. Must match a key inside drivers.Reads from the environment variable MODEL_SCRIBE_DRIVER. Defaults to 'database'.Supported built-in values: "database", "file", "stack".
​
drivers
array
required
A map of driver name → driver configuration block. Each entry must contain at least a driver key that identifies the driver type. See the Driver blocks section below for the full schema of each built-in driver.
​
capture_request_context
bool
When true, ModelScribe automatically attaches the current HTTP request URL, client IP address, and User-Agent string to every log entry. Disable this if you are logging from CLI contexts only or want a leaner storage footprint.Defaults to true.
​
auth_guard
string|null
The Laravel authentication guard used to resolve the currently authenticated user (the “causer”). When null, ModelScribe calls Auth::user() using whatever guard is active at the time of the event.Set this to a specific guard name (e.g. 'web', 'api') when your application uses multiple guards and you always want a particular one to be the source of the causer.Defaults to null.
​
guard_stores
array
Maps a guard name to a named store. When a model’s $auditLogName is 'default', ModelScribe checks the currently active guard against this map and rewrites the log name before routing to the database driver.
'guard_stores' => [
    'api' => 'invoices',
    'web' => 'orders',
],
See Multi-Table Routing for the full guard-routing workflow.

​
Driver blocks

​
database

The database driver persists audit entries to one or more database tables via Eloquent. It is the default driver and supports named stores, custom connections, and retention policies.
​
drivers.database.driver
string
required
Must be "database".
​
drivers.database.connection
string|null
The Laravel database connection name to use for writes and pruning. When null, the application’s default connection is used.Reads from MODEL_SCRIBE_DB_CONNECTION. Defaults to null.
​
drivers.database.table
string
The default table name for models that do not define a specific named store via $auditLogName.Reads from MODEL_SCRIBE_TABLE. Defaults to 'model_scribe_logs'.
​
drivers.database.stores
array
A map of store name → store configuration used for multi-table routing. Each entry can contain:
  • tables (array) — one or more table names to write to simultaneously
  • connection (string|null) — override the DB connection for this store
  • auth_guard (string|null) — override the causer guard for this store
When empty (the default), all models write to the single table defined above. See Multi-Table Routing for a detailed walkthrough.
​
drivers.database.retention
array
Controls how long records are kept when model-scribe:prune runs. Contains three sub-keys:
  • type — 'permanent', 'days', or 'rotating'; reads MODEL_SCRIBE_RETENTION
  • days — number of days to retain records when type is 'days'; reads MODEL_SCRIBE_RETENTION_DAYS; default 90
  • keep — maximum number of records per table when type is 'rotating'; reads MODEL_SCRIBE_RETENTION_KEEP; default 500
See Retention for the full policy reference.
​
drivers.database.auth_guard
string|null
Per-driver causer guard override. Supersedes the global auth_guard value for entries written through this driver. Defaults to null.

​
file

The file driver writes audit entries to Laravel’s logging system as structured info-level log messages, including the full entry context as JSON.
​
drivers.file.driver
string
required
Must be "file".
​
drivers.file.channel
string
Any channel name defined in config/logging.php. The entry is dispatched via Log::channel($channel)->info(...).Reads from MODEL_SCRIBE_LOG_CHANNEL. Defaults to 'daily'.
​
drivers.file.auth_guard
string|null
Per-driver causer guard override. Defaults to null.

​
stack

The stack driver fans a single log entry out to multiple other named drivers simultaneously. It is useful when you want both a queryable database record and a log-file trail for every event.
​
drivers.stack.driver
string
required
Must be "stack".
​
drivers.stack.drivers
array
An ordered list of driver names (keys from the drivers map) to forward each entry to. Every listed driver receives the same LogEntry object.
'drivers' => ['database', 'file'],
​
drivers.stack.auth_guard
string|null
Per-driver causer guard override. Note that each downstream driver in the stack may also define its own auth_guard. Defaults to null.
Every driver block — database, file, stack, and any custom driver — supports its own auth_guard key. A value set there takes precedence over the global auth_guard setting at the top of the config file, giving you fine-grained control over which guard resolves the causer for each storage destination.

Build docs developers (and LLMs) love

Get started for freeTalk to us