Filament Logger Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mradder/filament-logger
   php artisan filament-logger:install
   php artisan migrate
   

2. Register the Activity Resource: In your Filament panel provider:

   public function panel(Panel $panel): Panel {
       return $panel->resources([
           config('filament-logger.activity_resource'),
       ]);
   }
   

3. First Use Case:

   • Immediately access the Activity Log resource in Filament to view all tracked actions (model CRUD, auth events, etc.).
   • Use the built-in dashboard widgets (e.g., "Top Users," "High-Risk Actions") for at-a-glance monitoring.

Implementation Patterns

Core Workflows

1. Model Lifecycle Logging: Automatically logs create, update, delete, restore, forceDelete, and replicate events for Eloquent models.

   // No manual setup needed—just use Eloquent as usual.
   User::create([...]); // Auto-logged
   

2. Auth Event Tracking: Logs logins, logouts, failed attempts, lockouts, and password resets.

   // Configure guards in config/filament-logger.php:
   'access' => [
       'guards' => ['web'], // Only log 'web' guard events
   ]
   

3. Custom Domain Events: Dispatch custom events for domain-specific logging:

   use MrAdder\FilamentLogger\Facades\FilamentLogger;
   
   FilamentLogger::dispatch('payment.processed', [
       'amount' => 100,
       'user_id' => 1,
   ]);
   

4. Alerting: Trigger alerts for sensitive actions (e.g., bulk deletes):

   // In config/filament-logger.php:
   'alerts' => [
       'rules' => [
           'bulk_delete' => [
               'event' => 'eloquent.force_delete',
               'webhook' => 'https://your-webhook.example',
           ],
       ],
   ]
   

5. Data Exports: Export filtered logs via the Filament UI (CSV/JSON) or programmatically:

   use MrAdder\FilamentLogger\Facades\FilamentLogger;
   
   $logs = FilamentLogger::activity()
       ->where('log_name', 'users')
       ->latest()
       ->get();
   

Integration Tips

• Resource-Specific Logging: Override default logging for a resource by publishing the config:

  php artisan vendor:publish --provider="MrAdder\FilamentLogger\FilamentLoggerServiceProvider" --tag="config"
  

  Then configure resources in config/filament-logger.php:

  'resources' => [
      'posts' => [
          'ignore' => ['updated_at', 'deleted_at'],
      ],
  ],
  

• Pruning Old Logs: Schedule the prune command in app/Console/Kernel.php:

  $schedule->command('filament-logger:prune')->daily();
  

• Dashboard Widgets: Add widgets to your Filament dashboard:

  public function widgets(Panel $panel): array {
      return [
          \MrAdder\FilamentLogger\Widgets\ActivityOverview::class,
          \MrAdder\FilamentLogger\Widgets\TopUsers::class,
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Authorization:

   • The activity resource enforces strict authorization by default. Ensure you register a policy:

     use MrAdder\FilamentLogger\Models\Activity;
     
     Gate::define('viewActivity', fn ($user) => $user->isAdmin());
     

   • Disable strict checks in config/filament-logger.php if needed:

     'security' => [
         'strict_authorization' => false,
     ],
     

2. Sensitive Data:

   • Passwords, tokens, and secrets are auto-redacted in logs. For additional fields, use:

     'sanitize' => [
         'fields' => ['api_token', 'secret_key'],
     ],
     

3. Multi-Guard Apps:

   • Auth events (e.g., Login, Failed) respect the guards config. Events without a guard (e.g., PasswordReset) are always logged.

4. Historical Data:

   • Older logs may contain unsanitized data. Use the filament-logger:prune command to clean up:

     php artisan filament-logger:prune --dry-run
     

Debugging

• Log Levels: Check the log_name in the database to identify which logger generated an entry (e.g., users, auth, custom).

• Custom Events: Verify events are dispatched correctly by checking the description field in the Activity model:

  // Debug custom event payloads:
  FilamentLogger::dispatch('test.event', ['debug' => true]);
  

• Performance: Large payloads (e.g., JSON fields) are collapsible in the UI. For bulk operations, consider:

  'resources' => [
      'posts' => [
          'ignore' => ['content'], // Exclude large fields
      ],
  ],
  

Extension Points

1. Custom Alert Handlers: Extend alert logic by binding a custom handler:

   FilamentLogger::extendAlertHandler(function ($event, $payload) {
       // Custom logic (e.g., Slack notifications)
   });
   

2. Model Observers: Override default logging for a model:

   use MrAdder\FilamentLogger\Observers\ActivityLogger;
   
   class UserObserver extends ActivityLogger {
       public function loggingEvent($model, $eventName, $changes) {
           // Custom logic before logging
           return parent::loggingEvent($model, $eventName, $changes);
       }
   }
   

3. UI Customization: Publish the Filament resource views:

   php artisan vendor:publish --provider="MrAdder\FilamentLogger\FilamentLoggerServiceProvider" --tag="views"
   

   Then override templates in resources/views/vendor/filament-logger/....

4. Pruning Logic: Customize pruning rules in config/filament-logger.php:

   'pruning' => [
       'rules' => [
           'users' => ['age' => '30 days'],
           'auth' => ['age' => '90 days'],
       ],
   ],