Installing ModelScribe: Composer, Config, and Migrate

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

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

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.

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"

What columns does the migration create?

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']);
});

Column	Type	Notes
`id`	bigint (auto-increment)	Primary key
`log_name`	string	Defaults to `'default'`; used for store routing
`event`	string	e.g. `created`, `updated`, `deleted`
`description`	text	Nullable; used by manual log entries
`causer_type` / `causer_id`	nullableMorphs	The authenticated user who triggered the action
`subject_type` / `subject_id`	nullableMorphs	The Eloquent model that was changed
`properties`	json	Holds `old` and `attributes` (new values) snapshots
`url`	text	Full request URL at the time of the change
`ip_address`	ipAddress	Client IP address
`user_agent`	string	HTTP User-Agent header value
`batch_uuid`	uuid	Groups related operations into a single batch
`tags`	json	Arbitrary searchable tags from `$auditTags`
`created_at` / `updated_at`	timestamps	Standard Laravel timestamps

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.

Variable	Default	Description
`MODEL_SCRIBE_DRIVER`	`database`	The default driver to use (`database`, `file`, or `stack`)
`MODEL_SCRIBE_DB_CONNECTION`	`null` (app default)	Override the database connection used by the database driver
`MODEL_SCRIBE_TABLE`	`model_scribe_logs`	The default database table name for audit entries
`MODEL_SCRIBE_RETENTION`	`permanent`	Retention policy type: `permanent`, `days`, or `rotating`
`MODEL_SCRIBE_RETENTION_DAYS`	`90`	Number of days to retain records when using the `days` policy
`MODEL_SCRIBE_RETENTION_KEEP`	`500`	Max records to keep per subject when using the `rotating` policy

Getting Started

Core Concepts

Usage

Configuration

Maintenance

Installing ModelScribe: Composer, Config, and Migrate

Install the Package

Environment Variables

​Install the Package

​Environment Variables

Install the Package

Environment Variables