laravel-audit-trail maintained by jeevanjoshi
Laravel Audit Trail
A powerful, zero-configuration audit trail package for Laravel. Automatically tracks every create, update, and delete on your Eloquent models with a beautiful built-in dashboard.
Features
- Automatic model change tracking — just add one trait
- Records old and new values for every change
- Captures who made the change, from which IP, and when
- Beautiful built-in dashboard at
/audit-trail - One-click revert to any previous state
- Expandable diff view for changes
- Filterable by model, action, user, date range
- Fully configurable via config file
- Excludes sensitive fields like passwords automatically
- Works with any model — User, Invoice, Order, anything
Requirements
- PHP 8.1 or higher
- Laravel 9 to 12
Installation
Install via Composer:
composer require jeevanjoshi/laravel-audit-trail
The package will be auto-discovered by Laravel. No manual configuration needed.
Setup
1. Publish and run the migration
php artisan vendor:publish --tag=audit-trail-migrations
php artisan migrate
This creates the audit_trails table in your database.
2. Add the trait to any model you want to track
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Jeevanjoshi\LaravelAuditTrail\Traits\HasAuditTrail;
class User extends Model
{
use HasAuditTrail;
}
That's it. Every create, update, and delete on this model is now tracked automatically.
Dashboard
Visit the audit trail dashboard at: https://your-app.com/audit-trail
The dashboard shows:
- Total changes, today's changes, deletions, active users
- Full change history with old and new values
- Filters by model, action, model ID, and date range
- Revert button to restore any previous state
By default the dashboard is protected by auth middleware. Make sure your app has authentication set up.
Querying Audit History
// Get all audit history for a specific record
$user->audits()->get();
// Get only updates
$user->audits()->ofAction('updated')->get();
// Get latest audit
$user->latestAudit();
// Check if model has any history
$user->hasAuditHistory();
// Get paginated history
$user->audits()->latest()->paginate(20);
Reverting Changes
// Revert a record to its previous state
$audit = $user->audits()->latest()->first();
$user->revertTo($audit->id);
// Returns true on success, false on failure
Silent Updates (without logging)
// This update will NOT be logged
$user->withoutAudit(function () use ($user) {
$user->update(['last_seen_at' => now()]);
});
Useful for updates that aren't meaningful — like updating timestamps, counters, or cache fields.
Excluding Fields Per Model
class User extends Model
{
use HasAuditTrail;
// These fields will never be logged for this model
protected array $auditExclude = [
'two_factor_secret',
'last_seen_at',
];
}
Configuration
Publish the config file:
php artisan vendor:publish --tag=audit-trail-config
This creates config/audit-trail.php in your application:
return [
// Enable or disable the package entirely
'enabled' => env('AUDIT_TRAIL_ENABLED', true),
// Your user model
'user_model' => env('AUDIT_TRAIL_USER_MODEL', 'App\Models\User'),
// Dashboard URL prefix
// Default: your-app.com/audit-trail
'route_prefix' => env('AUDIT_TRAIL_ROUTE_PREFIX', 'audit-trail'),
// Middleware protecting the dashboard
'middleware' => ['web', 'auth'],
// Fields never logged across ALL models
'exclude_fields' => [
'password',
'remember_token',
'two_factor_secret',
'two_factor_recovery_codes',
'updated_at',
],
// Auto delete logs older than X days (null = keep forever)
'keep_for_days' => env('AUDIT_TRAIL_KEEP_DAYS', null),
// Records per page on dashboard
'per_page' => env('AUDIT_TRAIL_PER_PAGE', 20),
// Dashboard title
'dashboard_title' => env('AUDIT_TRAIL_TITLE', 'Audit Trail'),
];
Customizing the Dashboard UI
Publish the views to customize them:
php artisan vendor:publish --tag=audit-trail-views
This copies the views to resources/views/vendor/audit-trail/ in your application. Edit them freely — they won't be overwritten when you update the package.
Environment Variables
Add these to your .env to configure without touching the config file:
AUDIT_TRAIL_ENABLED=true
AUDIT_TRAIL_ROUTE_PREFIX=audit-trail
AUDIT_TRAIL_KEEP_DAYS=90
AUDIT_TRAIL_PER_PAGE=20
AUDIT_TRAIL_TITLE=Audit Trail
Real World Use Cases
- Hospital systems — track who changed patient records and when
- Financial apps — full audit log of every transaction change
- SaaS apps — show teams what changed in their account
- eCommerce — track order and inventory changes
- HR systems — log every change to employee records
- Any app — know exactly what changed, who changed it, and when
Available Scopes
// Filter by action
Audit::ofAction('created')->get();
Audit::ofAction('updated')->get();
Audit::ofAction('deleted')->get();
// Filter by model
Audit::forModel(User::class)->get();
// Filter by user
Audit::byUser($userId)->get();
// Filter by date
Audit::today()->get();
Audit::thisMonth()->get();
Security
The dashboard is protected by auth middleware by default. To add additional protection:
// config/audit-trail.php
'middleware' => ['web', 'auth', 'can:view-audit-trail'],
Sensitive fields like password and remember_token are never logged regardless of configuration.
Testing
composer test
Cleaning Old Logs
Run the cleanup command manually:
php artisan audit-trail:clean
The command will:
- Check how many logs are older than
keep_for_days - Ask for confirmation before deleting
- Show how many records were deleted
Changelog
v1.0.0
- Initial release
- Automatic model change tracking
- Built-in dashboard with filters
- Revert to previous state
- Configurable excluded fields
- Per-model field exclusions
- Silent updates with withoutAudit()
License
MIT License. See LICENSE for more information.
Author
Jeevan Joshi
- GitHub: @thecrazydiamond1
- Email: joshijeewon18@gmail.com