Filament Activity Log Laravel Package

Technical Evaluation

Architecture Fit

• Core Alignment: The package bridges Spatie’s Laravel Activity Log (a robust audit-logging solution) with Filament Admin (a modern Laravel admin panel), making it ideal for applications requiring fine-grained activity tracking (e.g., CRUD operations, user actions, system events) within a Filament-based dashboard.
• Extensibility: Leverages Filament’s resource-based architecture, allowing TPMs to integrate logging per-model or globally without disrupting existing workflows. Compatible with Filament’s widgets, policies, and notifications for enriched UX.
• Data Flow: Logs are stored in the database (via Spatie’s activity_log table), enabling query-based filtering (e.g., by user, model, timestamp) via Filament’s built-in query builder or custom widgets.

Integration Feasibility

• Prerequisites:
  • Laravel 10.x+ (Filament v3.x compatibility).
  • Spatie’s laravel-activitylog package (v3.x) as a dependency.
  • Filament Admin (v3.x) installed.
• Hooks & Events:
  • Uses Filament’s registerResources and boot methods for seamless integration.
  • Supports model observers or Filament’s afterSave/afterDelete hooks for custom logging logic.
• Database Schema: Minimal schema changes required (Spatie’s default activity_log table is auto-migrated).

Technical Risk

• Version Lock: Tight coupling with Filament v3.x and Laravel 10.x may limit flexibility if upgrading to newer major versions. Risk mitigated by:
  • Monitoring Filament/Spatie’s backward-compatibility policies.
  • Testing against Filament’s beta channels early.
• Performance:
  • Logging high-frequency actions (e.g., real-time updates) could impact DB performance. Mitigate via:
    • Batch logging (e.g., queue delayed writes).
    • Selective logging (e.g., exclude low-value models).
  • Spatie’s package includes optimizations (e.g., logOnly for specific fields).
• Customization Overhead:
  • Advanced use cases (e.g., custom log fields, multi-tenancy) may require extending Spatie’s log model or Filament’s widget classes.

Key Questions

1. Audit Scope:
   • Should logging cover all models or only critical ones (e.g., User, Order)?
   • Are there sensitive fields (e.g., passwords) that must be redacted or excluded?
2. Retention Policy:
   • How long should logs be retained? (Affects DB size and cleanup strategies.)
3. Access Control:
   • Who should view/edit logs? (Leverage Filament’s role-based permissions.)
4. Alerting:
   • Should logs trigger notifications (e.g., Slack alerts for suspicious activity)?
5. Export/Compliance:
   • Are there GDPR/legal requirements for log export or deletion?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native compatibility with:
  • Filament Admin (v3.x) for UI integration.
  • Spatie’s Activity Log (v3.x) for core logging.
  • Laravel Queues (optional) for async logging.
• Database: Supports MySQL, PostgreSQL, SQLite (via Spatie’s package).
• Frontend: Filament’s Blade/Inertia/Vue support ensures logs render in existing admin panels.

Migration Path

1. Prerequisites:
   • Install via Composer:

     composer require pxlrbt/filament-activity-log
     

   • Publish package assets (config, migrations):

     php artisan vendor:publish --provider="Pxlrbt\FilamentActivityLog\FilamentActivityLogServiceProvider"
     

   • Run migrations:

     php artisan migrate
     

2. Basic Integration:
   • Register the ActivityLog widget in app/Providers/Filament/AdminPanelProvider.php:

     public function panel(Panel $panel): Panel
     {
         return $panel
             ->widgets([
                 \Pxlrbt\FilamentActivityLog\Widgets\ActivityLogWidget::class,
             ]);
     }
     

3. Advanced Customization:
   • Extend Log Model: Override Pxlrbt\FilamentActivityLog\Models\ActivityLog for custom fields.
   • Filter Logs: Use Filament’s widget filters or build a custom query scope.
   • Async Logging: Wrap log calls in a queue job:

     use Illuminate\Support\Facades\Queue;
     
     Queue::later(now()->addSeconds(5), fn () => Activity::log(...));
     

Compatibility

• Filament Plugins: Works alongside other Filament plugins (e.g., Filament Forms/Tables) without conflicts.
• Monorepos: If using Laravel Packages, ensure the package is auto-discoverable or manually bootstrapped.
• Testing:
  • Unit test log creation (e.g., mock Filament actions).
  • E2E test widget rendering and permission gates.

Sequencing

1. Phase 1: Basic logging for core models (e.g., User, Post).
2. Phase 2: Add widget filters, export functionality, and alerts.
3. Phase 3: Optimize for high-volume logs (e.g., queueing, archiving).
4. Phase 4: Extend for multi-tenancy or custom log formats.

Operational Impact

Maintenance

• Dependencies:
  • Monitor Filament/Spatie updates for breaking changes.
  • Pin versions in composer.json if stability is critical:

    "require": {
        "pxlrbt/filament-activity-log": "^1.0",
        "spatie/laravel-activitylog": "^3.0"
    }
    

• Log Rotation:
  • Implement database maintenance (e.g., php artisan activitylog:prune for Spatie’s package).
  • Consider partitioning the activity_log table for large datasets.

Support

• Troubleshooting:
  • Common issues:
    • Missing logs: Verify Filament’s resource registration and model observers.
    • Permission errors: Check Filament’s user policies.
  • Debug with:

    php artisan activitylog:list  # Spatie’s CLI tool
    

• Documentation:
  • Maintain a runbook for:
    • Log retention policies.
    • Widget customization (e.g., overriding templates).
    • Performance tuning (e.g., indexing activity_log table).

Scaling

• Performance Bottlenecks:
  • High Write Volume: Offload to a dedicated queue (e.g., activity:log job).
  • Query Performance: Add indexes to activity_log:

    Schema::table('activity_log', function (Blueprint $table) {
        $table->index('log_name');
        $table->index('properties');
        $table->index(['created_at', 'subject_type']);
    });
    

• Horizontal Scaling:
  • Logs are database-backed; ensure DB can handle read/write loads.
  • For global apps, consider sharding logs by tenant/region.

Failure Modes

Ramp-Up

• Onboarding:
  • Developers:
    • Document logging conventions (e.g., when to use Activity::log() vs. Filament hooks).
    • Provide starter templates for custom log formats.
  • QA:
    • Test edge cases (e.g., nested model updates, bulk actions).
    • Validate log accuracy against manual audits.
• Training:
  • Workshop: Demo how to:
    • Add logging to a new Filament resource.
    • Filter logs via the widget.
    • Extend the log model for custom data.
  • Cheat Sheet: Quick reference for:
    • Common log