Filament Auditing Laravel Package

Getting Started

Minimal Setup

1. Prerequisites:

   • Install laravel-auditing via Composer:

     composer require owen-it/laravel-auditing
     

   • Publish its config and run migrations:

     php artisan vendor:publish --provider="OwenIt\Auditing\AuditingServiceProvider"
     php artisan migrate
     

2. Install the plugin:

   composer require tapp/filament-auditing
   

3. Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Tapp\FilamentAuditing\FilamentAuditingPlugin::make(),
           ]);
   }
   

4. First use case: Add the HasAudits trait to your Filament resource model and include the audit relation manager in your resource:

   use Tapp\FilamentAuditing\Concerns\HasAudits;
   
   class PostResource extends Resource
   {
       public static function form(Form $form): Form
       {
           return $form
               ->schema([
                   // ... your fields
               ]);
       }
   
       public static function table(Table $table): Table
       {
           return $table
               ->columns([
                   // ... your columns
               ])
               ->relations([
                   'audits' => AuditRelationManager::make(),
               ]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Audit Tracking:

   • Enable auditing for a model by adding the HasAudits trait and configuring audit() in the model:

     use OwenIt\Auditing\Contracts\Auditable;
     use Tapp\FilamentAuditing\Concerns\HasAudits;
     
     class Post implements Auditable
     {
         use HasAudits;
     
         public static function audit(): array
         {
             return [
                 'title', 'content', 'published_at',
             ];
         }
     }
     

2. Resource Integration:

   • View/Edit Pages: Automatically shows audits in a collapsible panel.
   • Table Relation: Add AuditRelationManager to your resource’s relations() method:

     ->relations([
         'audits' => AuditRelationManager::make()
             ->searchable(['old_values', 'new_values', 'created_at'])
             ->sortable(['created_at'])
             ->paginated(10),
     ])
     

3. Restore Functionality:

   • Click the "Restore" button in the audit table to revert changes. The plugin handles:
     • Soft-deletes (if enabled in laravel-auditing).
     • Field-specific rollbacks (e.g., title or content).

4. Customization:

   • Override the audit table columns/filters:

     AuditRelationManager::make()
         ->columns([
             Tables\Columns\TextColumn::make('old.title')
                 ->label('Previous Title'),
             Tables\Columns\TextColumn::make('new.title')
                 ->label('Current Title'),
             Tables\Columns\TextColumn::make('created_at')
                 ->dateTime(),
         ])
     

5. Bulk Actions:

   • Filter audits by:
     • User (created_by).
     • Date range (created_at).
     • Changed fields (old_values/new_values).

Advanced Patterns

1. Dynamic Audit Fields: Dynamically include/exclude fields based on user roles or conditions:

   public static function audit(): array
   {
       $fields = ['title', 'content'];
       if (auth()->user()->isAdmin()) {
           $fields[] = 'deleted_at';
       }
       return $fields;
   }
   

2. Audit Policies: Use Laravel’s Policy to restrict audit access:

   class PostPolicy
   {
       public function viewAudits(User $user, Post $post)
       {
           return $user->isAdmin();
       }
   }
   

   Then register the policy in AuditRelationManager:

   AuditRelationManager::make()
       ->policy(PostPolicy::class)
   

3. Export Audits: Combine with Filament’s ExportAction to export audit logs:

   use Filament\Tables\Actions\ExportAction;
   
   AuditRelationManager::make()
       ->actions([
           ExportAction::make()
               ->filename('audit-logs-' . now()->format('Y-m-d')),
       ])
   

4. Real-Time Notifications: Trigger notifications when critical audits occur (e.g., published_at changes):

   protected static function booted()
   {
       static::saved(function ($model) {
           if ($model->wasChanged('published_at')) {
               Notification::send(
                   auth()->user(),
                   new AuditNotification($model->audits()->latest()->first())
               );
           }
       });
   }
   

Gotchas and Tips

Common Pitfalls

1. Missing laravel-auditing Setup:

   • Error: Class 'OwenIt\Auditing\Contracts\Auditable' not found.
   • Fix: Ensure owen-it/laravel-auditing is installed and the Auditable trait is used in your model.

2. Audit Table Not Showing:

   • Cause: Forgetting to add HasAudits trait or audit() method to the model.
   • Fix: Verify the model implements Auditable and the trait is included.

3. Restore Fails Silently:

   • Cause: The audit record lacks old_values or new_values (e.g., non-tracked fields).
   • Fix: Ensure all restored fields are included in the audit() array.

4. Permission Denied:

   • Cause: Missing Filament permissions for the resource.
   • Fix: Add canView/canEdit to the resource’s getPages() or use policies.

5. Performance Issues:

   • Cause: Loading too many audits for a model.
   • Fix: Limit audits with paginated() or limit():

     AuditRelationManager::make()->paginated(20)
     

Debugging Tips

1. Check Audit Logs:

   • Query the audits table directly:

     php artisan tinker
     >>> \App\Models\Post::first()->audits()->latest()->get();
     

2. Enable Query Logging:

   • Temporarily enable in AppServiceProvider:

     public function boot()
     {
         DB::enableQueryLog();
     }
     

   • Inspect logs after interacting with the audit panel.

3. Clear Cached Views:

   • If changes to the audit table aren’t reflected:

     php artisan view:clear
     php artisan cache:clear
     

Configuration Quirks

1. Soft Deletes:

   • Ensure laravel-auditing is configured for soft deletes in config/auditing.php:

     'soft_deletes' => true,
     

2. Custom Audit Model:

   • If using a custom audit model (e.g., App\Models\Audit), extend the plugin’s config:

     'model' => \App\Models\Audit::class,
     

     in config/filament-auditing.php.

3. Field-Specific Rollbacks:

   • The plugin restores all changed fields in an audit. To exclude fields:

     public static function audit(): array
     {
         return [
             'title' => ['except' => ['slug']], // Skip 'slug' during rollback
         ];
     }
     

Extension Points

1. Custom Audit Actions:

   • Add actions to the audit table (e.g., "Revert All"):

     AuditRelationManager::make()
         ->actions([
             Tables\Actions\Action::make('revertAll')
                 ->action(function (Audit $record) {
                     // Custom logic
                 }),
         ])
     

2. Override Audit Table:

   • Replace the default table with a custom one:

     use Tapp\FilamentAuditing\Tables\AuditTable;
     
     AuditRelationManager::make()
         ->table(AuditTable::class)
     

3. Hook into Audit Events:

   • Listen for audit.created or audit.restored events:

     event(new AuditCreated($audit));
     

     Register listeners in EventServiceProvider.

4. Localization:

   • Translate labels/actions by publishing the plugin’s lang files:

     php artisan vendor:publish --tag=filament-auditing-lang
     

   • Override in resources/lang/vendor/filament-auditing/.