Filament Auditing Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: Seamlessly extends Filament’s resource panels with audit trail functionality, aligning with Filament’s modular architecture. Leverages Filament’s built-in relation managers for consistency.
• Laravel Auditing Dependency: Relies on laravel-auditing, a battle-tested package for audit logging. This reduces reinvention but requires adherence to its model/event-based architecture.
• UI/UX Alignment: Provides a native Filament table view for audits, maintaining visual parity with other resource managers (e.g., HasMany, BelongsTo). Reduces cognitive load for developers familiar with Filament.
• Data Model Assumptions:
  • Assumes models are already configured with HasAudit trait (from laravel-auditing).
  • Audit tables must follow laravel-auditing's default schema (e.g., audits table with auditable_id, event, old_values, etc.).
  • Risk: Custom audit table schemas or non-standard event structures may require middleware or decorators.

Integration Feasibility

• Low-Coupling Design: Plugin injects audit relations via Filament’s RelationManager interface, minimizing direct model/controller modifications.
• Configuration Over Convention: Supports customization via FilamentAuditingConfig (e.g., excluded fields, custom columns). Example:

  FilamentAuditing::configureUsing(function (FilamentAuditingConfig $config) {
      $config->excludeFields(['password', 'api_token']);
  });
  

• Event-Driven Hooks: Extends laravel-auditing events (e.g., RetrievingAudit, RestoringAudit) for pre/post-processing.
• Filament 3/4/5 Support: Backward-compatible with major Filament versions, but Filament 2.x is deprecated (per compatibility table). Requires version alignment during adoption.

Technical Risk

Key Questions

1. Audit Scope:
   • Should audits be enabled for all models, or selectively (e.g., only User, Payment)?
   • How will audit data volume scale (e.g., 1M+ records)? Pagination/archiving needed?
2. Restore Workflow:
   • Does the team need custom validation before restoring audits (e.g., admin approval)?
   • Should restoration trigger additional actions (e.g., notifications, cascading updates)?
3. Compliance:
   • Are there legal requirements for audit retention/deletion (e.g., GDPR)? Plugin lacks built-in TTL.
4. Performance Budget:
   • What’s the acceptable latency for audit-heavy resources (e.g., Post with 10K audits)?
5. Filament Customization:
   • Will the team extend Filament’s UI (e.g., custom audit filters, bulk actions)? Plugin supports this via RelationManager overrides.

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Filament-based admin panels where audit trails are critical (e.g., SaaS platforms, financial systems, compliance-heavy apps).
• Tech Stack Synergy:
  • Laravel: Native integration with laravel-auditing (no polyfills needed).
  • Filament: Zero-config relation managers reduce boilerplate.
  • Database: Supports MySQL, PostgreSQL, SQLite (via laravel-auditing).
• Anti-Patterns:
  • Avoid for read-heavy apps where audit queries would dominate DB load.
  • Not suitable if audits require non-standard fields (e.g., custom metadata).

Migration Path

1. Prerequisite Setup:
   • Install laravel-auditing and configure models:

     composer require owen-it/laravel-auditing
     php artisan vendor:publish --provider="OwenIt\Auditing\AuditingServiceProvider"
     

   • Enable auditing for target models:

     use OwenIt\Auditing\Contracts\Auditable;
     use OwenIt\Auditing\Traits\Auditable as AuditableTrait;
     
     class User implements Auditable {
         use AuditableTrait;
     }
     

2. Plugin Installation:
   • Add to composer.json:

     "require": {
         "tapp/filament-auditing": "^4.0"
     }
     

   • Publish config:

     php artisan vendor:publish --provider="Tapp\FilamentAuditing\FilamentAuditingServiceProvider"
     

3. Resource Integration:
   • Attach the relation manager to Filament resources:

     use Tapp\FilamentAuditing\RelationManagers\AuditsRelationManager;
     
     protected static function getRelations(): array {
         return [
             AuditsRelationManager::make(),
         ];
     }
     

4. Customization (Optional):
   • Extend audit columns, filters, or restoration logic via RelationManager overrides.
   • Example: Add a "diff viewer" for old_values:

     AuditsRelationManager::make()->columns([
         Tables\Columns\TextColumn::make('event')->badge(),
         Tables\Columns\TextColumn::make('created_at')->dateTime(),
         Tables\Columns\TextColumn::make('changes')
             ->getStateUsing(fn ($record) => json_diff($record->old_values, $record->new_values)),
     ]);
     

Compatibility

• Filament Versions: Strictly adhere to the compatibility table. Mixing versions (e.g., Filament 5 + plugin 3.x) will fail.
• PHP Version: Requires PHP 8.1+ (aligned with Filament 4/5).
• Database: No schema migrations provided; relies on laravel-auditing's default audits table.
• Third-Party Conflicts:
  • Avoid if using spatie/laravel-activitylog or similar (duplicate audit tables).
  • Test with Filament plugins that modify ResourcePanel (e.g., filament-spatie-laravel-permission).

Sequencing

1. Phase 1: Pilot Model (2–3 days)
   • Enable auditing on a low-risk model (e.g., Tag).
   • Test relation manager UI and restoration workflow.
2. Phase 2: Core Models (1 week)
   • Roll out to critical models (User, Order, Post).
   • Monitor query performance (add DB::enableQueryLog() checks).
3. Phase 3: Customization (Ongoing)
   • Add filters, columns, or hooks as needed.
   • Implement archiving for old audits (e.g., move to audits_archive table).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor laravel-auditing and filament/filament for breaking changes.
  • Plugin releases are infrequent (last release: 2026-02-02); expect long-term support but minimal feature additions.
• Audit Schema Drift:
  • Changes to laravel-auditing’s table structure may require manual migrations.
  • Example: If laravel-auditing adds a deleted_at column, update the plugin’s queries.
• Plugin-Specific:
  • No built-in audit cleanup; schedule a cron job for archiving/deletion:

    php artisan schedule:run
    // In App\Console\Kernel.php
    $schedule->command(AuditArchiveCommand::class)->daily();
    

Support

• Troubleshooting:
  • Common issues:
    • "Audits not appearing": Verify HasAudit trait is applied and laravel-auditing is bootstrapped.
    • "Restore fails": Check for foreign key constraints or custom restoring event listeners.
  • Debugging tools:
    • php artisan audit:list (from laravel-auditing).
    • Filament’s RelationManager logs (enable via config/filament.php).
• Community:
  • Limited stars (114) and dependents (0) suggest niche adoption. Issues may require direct PRs.
  • GitHub discussions are the primary support channel.

**