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.

This page walks through everything you need to get ModelScribe running in a Laravel application: pulling in the package with Composer, publishing the configuration file and database migration, and running that migration to create the model_scribe_logs table. Once these four steps are complete you can start adding the HasAuditLog trait to your models.

​
Install the Package

1

Require the package via Composer

Add ModelScribe to your project’s dependencies with the following command. Laravel’s package auto-discovery will register the service provider and ModelScribe facade alias automatically — no manual registration is needed.
composer require hypathbel/model-scribe
2

Publish the configuration file

Publish the model-scribe.php configuration file to your application’s config/ directory. This file is where you define drivers, named stores, retention policies, and global settings.
php artisan vendor:publish --tag="model-scribe-config"
After running this command, a fully commented config/model-scribe.php file will be created. You can adjust the default driver, database connection, table name, and retention settings here — or leave the defaults and rely on environment variables instead.
3

Publish the database migration

Publish the migration stub that creates the model_scribe_logs table. The file will appear in your database/migrations/ directory with a standard timestamp prefix.
php artisan vendor:publish --tag="model-scribe-migrations"
The published migration creates the following schema:
Schema::create($tableName, function (Blueprint $table) {
    $table->id();

    // Organisation
    $table->string('log_name')->default('default');
    $table->string('event');
    $table->text('description')->nullable();

    // Causer — who performed the action (typically the authenticated user)
    $table->nullableMorphs('causer');   // causer_type, causer_id

    // Subject — the Eloquent model that was affected
    $table->nullableMorphs('subject');  // subject_type, subject_id

    // Changes — old + new attribute values
    $table->json('properties')->nullable();

    // Web context
    $table->text('url')->nullable();
    $table->ipAddress('ip_address')->nullable();
    $table->string('user_agent')->nullable();

    // Grouping and tagging
    $table->uuid('batch_uuid')->nullable();
    $table->json('tags')->nullable();

    $table->timestamps();

    // Optimised indices
    $table->index('log_name');
    $table->index('event');
    $table->index('batch_uuid');
    $table->index(['subject_type', 'subject_id']);
    $table->index(['causer_type', 'causer_id']);
});
ColumnTypeNotes
idbigint (auto-increment)Primary key
log_namestringDefaults to 'default'; used for store routing
eventstringe.g. created, updated, deleted
descriptiontextNullable; used by manual log entries
causer_type / causer_idnullableMorphsThe authenticated user who triggered the action
subject_type / subject_idnullableMorphsThe Eloquent model that was changed
propertiesjsonHolds old and attributes (new values) snapshots
urltextFull request URL at the time of the change
ip_addressipAddressClient IP address
user_agentstringHTTP User-Agent header value
batch_uuiduuidGroups related operations into a single batch
tagsjsonArbitrary searchable tags from $auditTags
created_at / updated_attimestampsStandard Laravel timestamps
4

Run the migration

Create the model_scribe_logs table in your database by running the standard migrate command.
php artisan migrate
Your database is now ready to receive audit log entries. Head to the Quickstart to add HasAuditLog to your first model.

​
Environment Variables

All of the most common configuration options can be set via environment variables in your .env file, so you don’t have to modify config/model-scribe.php directly.
Set MODEL_SCRIBE_DRIVER=file in your .env to switch the default driver to flat-file logging without touching any PHP configuration. This is useful during local development or in environments without a dedicated audit database.
VariableDefaultDescription
MODEL_SCRIBE_DRIVERdatabaseThe default driver to use (database, file, or stack)
MODEL_SCRIBE_DB_CONNECTIONnull (app default)Override the database connection used by the database driver
MODEL_SCRIBE_TABLEmodel_scribe_logsThe default database table name for audit entries
MODEL_SCRIBE_RETENTIONpermanentRetention policy type: permanent, days, or rotating
MODEL_SCRIBE_RETENTION_DAYS90Number of days to retain records when using the days policy
MODEL_SCRIBE_RETENTION_KEEP500Max records to keep per subject when using the rotating policy

Build docs developers (and LLMs) love

Get started for freeTalk to us