balouch/laravel-audit-log

Laravel Audit Log Package with UI

v1.0 2026-03-26 07:36 UTC

Requires

• php: ^8.1
• illuminate/support: ^12.0

MIT

• Muhammad Irshad Khan Balouch

README

A comprehensive Laravel audit log package that automatically tracks model changes and provides a beautiful UI for viewing audit trails.

Features

• Automatic Audit Logging: Simply add the Auditable trait to any model to start tracking changes
• Beautiful UI: Modern, responsive interface for viewing audit logs with filtering and search
• Detailed Change Tracking: Tracks old and new values for all model changes
• User & IP Tracking: Records which user made changes and from which IP address
• Bulk Operations: Delete multiple audit logs at once
• Configurable: Easy configuration options for excluding sensitive fields
• Laravel 12 Compatible: Built for the latest Laravel version

Installation

1. Install the package via Composer:

composer require balouch/laravel-audit-log

1. Publish the migration file:

php artisan vendor:publish --tag="audit-log-migrations"

1. Run the migration:

php artisan migrate

1. Publish the configuration file (optional):

php artisan vendor:publish --tag="audit-log-config"

1. Publish the views (optional, if you want to customize the UI):

php artisan vendor:publish --tag="audit-log-views"

1. Publish the routes (optional, if you want to customize the routes):

php artisan vendor:publish --tag="audit-log-routes"

Usage

Basic Setup

Add the Auditable trait to any model you want to track:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Balouch\AuditLog\Traits\Auditable;

class User extends Model
{
    use Auditable;

    // Optionally specify which attributes to exclude from audit logging
    protected $auditLogExcluded = [
        'last_login_at',
    ];
}

That's it! Now all changes to the User model will be automatically logged.

Accessing Audit Logs

You can access audit logs through the model relationship:

$user = User::find(1);
$auditLogs = $user->auditLogs; // All audit logs for this user
$latestLog = $user->getLatestAuditLog(); // Most recent audit log

Querying Audit Logs

use Balouch\AuditLog\Models\AuditLog;

// Get all audit logs
$logs = AuditLog::all();

// Filter by action
$logs = AuditLog::action('updated')->get();

// Filter by user
$logs = AuditLog::byUser($user)->get();

// Filter by model
$logs = AuditLog::forModel($user)->get();

// Complex queries
$logs = AuditLog::with('user')
    ->where('action', 'updated')
    ->whereDate('created_at', '>=', now()->subDays(30))
    ->latest()
    ->paginate(15);

UI Access

The package provides a web interface for viewing audit logs. By default, it's available at:

/audit-logs

Note: The routes are protected by the web and auth middleware by default. You can configure this in the published configuration file.

Configuration

After publishing the configuration file, you can customize the package behavior in config/audit-log.php:

return [
    'pagination' => [
        'per_page' => 15, // Number of items per page in the UI
    ],
    
    'middleware' => ['web', 'auth'], // Route middleware
    
    'route_prefix' => 'audit-logs', // URL prefix for audit log routes
    
    'excluded_attributes' => [ // Attributes to never log
        'password',
        'remember_token',
        'email_verified_at',
        'created_at',
        'updated_at',
    ],
    
    'auto_cleanup' => [ // Automatically clean up old logs
        'enabled' => false,
        'days' => 90,
    ],
];

Excluding Attributes

You can exclude specific attributes from being logged in two ways:

1. Global Configuration

Add attributes to the excluded_attributes array in the configuration file.

2. Model-Specific Exclusion

Add an auditLogExcluded property to your model:

class User extends Model
{
    use Auditable;
    
    protected $auditLogExcluded = [
        'last_login_at',
        'password_changed_at',
    ];
}

Audit Log Structure

Each audit log record contains:

• id: Unique identifier
• user_id: ID of the user who made the change (nullable)
• model_type: The fully qualified class name of the model
• model_id: The ID of the model instance
• action: The type of action (created, updated, deleted)
• old_values: JSON object of previous values (for updates and deletes)
• new_values: JSON object of new values (for creates and updates)
• ip_address: IP address of the user who made the change
• user_agent: User agent string of the browser
• created_at: When the audit log was created
• updated_at: When the audit log was last updated

UI Features

The provided web interface includes:

• List View: Paginated list of all audit logs with filtering options
• Detail View: Detailed view of individual audit logs showing all changes
• Filtering: Filter by action, model type, date range, and user
• Bulk Operations: Select and delete multiple audit logs at once
• Responsive Design: Works perfectly on desktop and mobile devices

Routes

The package registers the following routes:

• GET /audit-logs - List all audit logs
• GET /audit-logs/{auditLog} - Show audit log details
• DELETE /audit-logs/{auditLog} - Delete a specific audit log
• DELETE /audit-logs - Bulk delete audit logs

Security Considerations

• All routes are protected by authentication middleware by default
• Sensitive fields like passwords are automatically excluded from logging
• Consider who should have access to view audit logs in your application
• Regular cleanup of old audit logs is recommended to prevent database bloat

License

This package is open-sourced software licensed under the MIT license.

Support

For support, please open an issue on the GitHub repository or contact the package maintainer.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.