ModelScribe Drivers: Database, File, Stack, and Custom

A driver is the component responsible for the final step in the audit pipeline: taking a fully-assembled LogEntry DTO and persisting or dispatching it somewhere. ModelScribe ships with three built-in drivers, each implementing the DriverInterface contract, so they are all interchangeable and composable. The active driver is resolved at runtime by the DriverManager singleton, which caches each resolved instance for the lifetime of the request.

Built-in Drivers

Database
File
Stack

The database driver inserts a row into a database table for each audit event. It is the default driver and the most feature-rich, supporting multi-table routing, multiple DB connections, and configurable retention policies.

Store Resolution

When log() is called, the driver calls its internal resolveStore() method with the entry’s logName. Resolution follows this order:

Named store match. If a key under drivers.database.stores matches the logName, the driver uses that store’s tables (or table) and optional connection.
Global fallback. If no named store matches, the driver writes to the default table on the default connection.

A single named store can target multiple tables via the tables key — the entry is inserted into each table in the list. This is useful for writing the same audit record into both a partitioned archive table and a recent-events table.

Configuration

// config/model-scribe.php
'drivers' => [
    'database' => [
        'driver'     => 'database',
        'connection' => env('MODEL_SCRIBE_DB_CONNECTION', null),
        'table'      => env('MODEL_SCRIBE_TABLE', 'model_scribe_logs'),

        'stores' => [
            'invoices' => [
                'tables'     => ['invoice_scribe_logs', 'invoice_archive_logs'],
                'connection' => 'mysql_audit',
            ],
            'orders' => [
                'tables' => ['order_scribe_logs'],
            ],
        ],

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

Retention Policies

The database driver supports three retention modes, configured under retention.type:

Type	Behaviour
`permanent`	Records are never deleted automatically. This is the default.
`days`	Records older than `retention.days` days are deleted when `prune()` is called.
`rotating`	Only the most recent `retention.keep` records are kept per table managed by this driver.

Pruning is triggered by the model-scribe:prune Artisan command or by calling ModelScribe::prune() from a scheduled job.

The file driver writes each audit entry as a structured info-level log message to a Laravel log channel. It is well-suited for environments where you want audit records alongside your application logs, or where a database is unavailable.

What Gets Written

Each log line includes the description (or a default [event] logName label) as the message, and the full audit context — subject, causer, properties, tags, batch UUID, and request context — as structured key-value pairs in the log channel’s context.

Configuration

// config/model-scribe.php
'drivers' => [
    'file' => [
        'driver'  => 'file',

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

Point channel at any channel defined in your config/logging.php — stack, single, daily, papertrail, or a custom channel.

The file driver’s prune() method is intentionally a no-op that always returns 0. Log rotation and retention for file-based channels is handled natively by Laravel’s logging system (e.g., the daily channel automatically keeps a configurable number of days). There is nothing for ModelScribe to manage here.

The stack driver fans a single LogEntry out to multiple other named drivers in sequence. It holds no state of its own — it resolves each listed driver through the DriverManager and delegates both log() and prune() calls to all of them in order.

Configuration

// config/model-scribe.php
'drivers' => [
    'stack' => [
        'driver'  => 'stack',

        // Fan-out to these named drivers (resolved via DriverManager).
        'drivers' => ['database', 'file'],
    ],
],

The drivers array accepts any driver names that are defined in the drivers config block, including custom drivers. You can create multiple distinct stack configurations by adding additional named entries under drivers and pointing each at a different combination.

Pruning

When prune() is called on the stack driver, it delegates to each sub-driver’s prune() and returns the sum of all deleted records across every driver.

The stack driver is especially valuable for critical models — for example, financial records or permission changes — where you want both a queryable database record for reporting and a tamper-evident file-based trail as a secondary backup. If the database is unavailable, the file channel still captures the event.

Configuring the Default Driver

Set the default key to the name of the driver you want used for all models that do not specify their own:

// config/model-scribe.php
'default' => env('MODEL_SCRIBE_DRIVER', 'database'),

You can also set it via the MODEL_SCRIBE_DRIVER environment variable without touching the config file, which is useful for switching drivers per environment.

Overriding the Driver Per Model

A model can opt into a different driver by setting the $auditDriver property in the HasAuditLog trait:

use HypathBel\ModelScribe\Traits\HasAuditLog;

class PaymentTransaction extends Model
{
    use HasAuditLog;

    // Use the stack driver for this model, regardless of the global default.
    protected ?string $auditDriver = 'stack';
}

When $auditDriver is null (the default), the global default driver from config is used.

Custom Drivers

If the three built-in drivers do not cover your requirements — for example, you want to ship audit events to Elasticsearch, a message queue, or a webhook — you can register a custom driver using DriverManager::extend().

1. Implement `DriverInterface`

Your driver must implement the two-method DriverInterface contract:

use HypathBel\ModelScribe\Contracts\DriverInterface;
use HypathBel\ModelScribe\DTOs\LogEntry;

class ElasticsearchDriver implements DriverInterface
{
    public function __construct(protected array $config) {}

    public function log(LogEntry $entry): void
    {
        // Dispatch $entry to Elasticsearch using $this->config.
    }

    public function prune(): int
    {
        // Delete old entries and return the count, or return 0 if unsupported.
        return 0;
    }
}

2. Register via `extend()`

Call extend() on the DriverManager inside a service provider’s boot() method. The closure receives the driver’s config array and the DriverManager instance, and must return a DriverInterface implementation:

use HypathBel\ModelScribe\DriverManager;

public function boot(DriverManager $manager): void
{
    $manager->extend('elasticsearch', function (array $config, DriverManager $manager) {
        return new ElasticsearchDriver($config);
    });
}

3. Add the Driver Config Block

Add a matching entry under drivers in config/model-scribe.php:

'drivers' => [
    // ... built-in drivers ...

    'elasticsearch' => [
        'driver' => 'elasticsearch',
        'host'   => env('ELASTICSEARCH_HOST', 'localhost'),
        'port'   => env('ELASTICSEARCH_PORT', 9200),
        'index'  => env('MODEL_SCRIBE_ES_INDEX', 'model-scribe'),
    ],
],

The driver key inside the config block tells the DriverManager which registered creator to invoke when building this named driver instance. You can then set 'default' => 'elasticsearch' or use protected ?string $auditDriver = 'elasticsearch' on individual models.

Getting Started

Core Concepts

Usage

Configuration

Maintenance

ModelScribe Drivers: Database, File, Stack, and Custom

Built-in Drivers

Store Resolution

Configuration

Retention Policies

What Gets Written

Configuration

Configuration

Pruning

Configuring the Default Driver

Overriding the Driver Per Model

Custom Drivers

1. Implement `DriverInterface`

2. Register via `extend()`

3. Add the Driver Config Block

​Built-in Drivers

​Store Resolution

​Configuration

​Retention Policies

​What Gets Written

​Configuration

​Configuration

​Pruning

​Configuring the Default Driver

​Overriding the Driver Per Model

​Custom Drivers

​1. Implement DriverInterface

​2. Register via extend()

​3. Add the Driver Config Block

Built-in Drivers

Store Resolution

Configuration

Retention Policies

What Gets Written

Configuration

Configuration

Pruning

Configuring the Default Driver

Overriding the Driver Per Model

Custom Drivers

1. Implement `DriverInterface`

2. Register via `extend()`

3. Add the Driver Config Block