bhhaskin/laravel-audit

Audit trail package for Laravel applications with UUID support.

0.1.0 2025-11-02 08:06 UTC

Requires

• php: ^8.1
• illuminate/database: ^10.0|^11.0
• illuminate/support: ^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^8.0
• pestphp/pest: ^2.0
• phpunit/phpunit: ^10.5

MIT

• Bryan Haskin

README

Lightweight audit trail package for Laravel applications.

Features

• Records created, updated, deleted, and restored events for any model.
• Stores both numeric primary keys and UUIDs for audits, auditable models, and users.
• Captures before/after state, request metadata, and user attribution.
• Ships with ready-to-run migrations plus publishable stubs and configuration.

Installation

composer require bhhaskin/laravel-audit

Laravel auto-discovers the service provider. For older versions add LaravelAudit\AuditServiceProvider::class to the providers array in config/app.php.

Publish Assets

php artisan vendor:publish --provider="LaravelAudit\AuditServiceProvider" --tag=laravel-audit-config
php artisan vendor:publish --provider="LaravelAudit\AuditServiceProvider" --tag=laravel-audit-migrations

Run the migration:

php artisan migrate

Usage

1. Add the Auditable trait to any Eloquent model that you want to track.
2. Ensure the model has a uuid column populated via the included HasAuditUuid trait or your own logic.

use Illuminate\Database\Eloquent\Model;
use LaravelAudit\Traits\Auditable;
use LaravelAudit\Traits\HasAuditUuid;

class Post extends Model
{
    use HasAuditUuid;
    use Auditable;
}

Audits are exposed through the audits() relationship:

$post = Post::first();

foreach ($post->audits as $audit) {
    echo $audit->uuid; // Frontend-friendly identifier
}

Configuration

Published configuration (config/audit.php) lets you:

• Enable/disable the logger or specific events.
• Ignore fields such as timestamps when diffing changes.
• Add default metadata and provide a custom user resolver.

The default user resolver defers to Laravel's auth() helper. Implement a custom resolver by binding a callable class and updating user_resolver in the config.

Events

Two framework events are fired for each audit lifecycle:

• LaravelAudit\Events\AuditRecording (before persistence) exposes the proposed payload for last-minute tweaks.
• LaravelAudit\Events\AuditRecorded (after persistence) includes the saved Audit model instance.

Listen for these events to trigger notifications, broadcast changes, or enrich metadata.

License

MIT © Bryan

Testing

composer install
composer test