Filament Archivable Laravel Package

Technical Evaluation

Architecture Fit

• Filament Plugin Compatibility: The package is designed as a Filament plugin, leveraging Laravel’s Filament framework (v3.x) to extend resource tables with archiving functionality. This aligns well with projects already using Filament for admin panels, reducing UI/UX fragmentation.
• Eloquent Integration: Built atop laravel-archivable, it assumes Eloquent models with soft-deletion-like archiving logic (archived_at timestamp). Fit for CRUD-heavy apps where historical data retention is needed without hard deletes.
• Modularity: Lightweight (~500 LOC) and self-contained, minimizing coupling with core business logic. Ideal for incremental adoption (e.g., adding archiving to select resources).

Integration Feasibility

• Prerequisites:
  • Filament v3.x: Non-negotiable (plugin targets Filament’s table actions/filter system).
  • Eloquent Models: Requires models to support archivable trait (or manual archived_at column). Migration risk if models lack this structure.
  • PHP 8.1+: Aligns with Laravel 10+ Filament 3.x stack.
• Customization Hooks:
  • Supports custom archive/unarchive logic via ArchiveAction callbacks.
  • Filters can be extended (e.g., adding bulk actions).
  • Themeable: Uses Filament’s styling system (Tailwind CSS).

Technical Risk

• Dependency on Filament: Tight coupling with Filament’s table system may complicate multi-framework projects or future Filament major version upgrades.
• Soft-Delete Conflicts: Potential clashes with Laravel’s built-in SoftDeletes trait if both are used (e.g., archived_at vs. deleted_at). Mitigation: Explicitly document trait conflicts in architecture decisions.
• Testing Coverage: While CI includes tests, edge cases (e.g., concurrent archiving, large datasets) may need custom validation.
• Performance: Filtering on archived_at could impact queries if not indexed. Recommendation: Add DB index for archived_at during migration.

Key Questions

1. Does the project use Filament v3.x? If not, assess rewrite effort vs. alternative solutions (e.g., custom table actions).
2. Are Eloquent models already archivable? If not, evaluate migration cost (adding archived_at column/trait to models).
3. How critical is auditability? The package lacks built-in event logging (e.g., tracking who archived records). Plan for custom observers if needed.
4. Will archiving trigger workflows? (e.g., notifications, data transformations). The package is UI-only; business logic must be handled separately.
5. Scalability needs: For high-volume tables, test performance with archived_at filters under load.

Integration Approach

Stack Fit

• Primary Use Case: Admin panels in Laravel apps using Filament for resource management (e.g., CMS, SaaS dashboards, internal tools).
• Alternatives Considered:
  • Custom Solution: Rolling your own table actions/filters would require ~20–40 hours of dev time (vs. ~1 hour for this package).
  • Other Filament Plugins: No direct competitors exist for archiving; alternatives like spatie/laravel-filament-resource-table lack archiving features.
• Tech Stack Synergy:
  • Laravel: Native Eloquent support.
  • Filament: Plugin leverages Filament’s action/filter system, reducing boilerplate.
  • Tailwind CSS: Plugin styles are themeable, matching Filament’s design system.

Migration Path

1. Preparation:
   • Add archived_at column to target models (if missing):

     Schema::table('models', function (Blueprint $table) {
         $table->timestamp('archived_at')->nullable()->after('deleted_at');
     });
     

   • Install dependencies:

     composer require okeonline/filament-archivable joelbutcher/laravel-archivable
     

2. Implementation:
   • Register the plugin in app/Providers/Filament/PluginServiceProvider.php:

     public function register(): void
     {
         $this->plugin(ArchivablePlugin::make());
     }
     

   • Attach actions/filters to Filament resources:

     public static function table(Table $table): Table
     {
         return $table
             ->actions([
                 ArchivableAction::make(),
             ])
             ->filters([
                 ArchivedFilter::make(),
             ]);
     }
     

3. Post-Integration:
   • Testing: Validate archiving/unarchiving logic, filters, and edge cases (e.g., archiving already-archived records).
   • Documentation: Update runbooks for data retention policies (e.g., "Archived records are retained for 5 years").

Compatibility

• Filament Versions: Tested with Filament 3.x. Not compatible with Filament 2.x or other admin panels (e.g., Nova).
• Laravel Versions: Requires Laravel 10+ (PHP 8.1+). Downgrade risk if using older Laravel.
• Database: Supports MySQL, PostgreSQL, SQLite (via Eloquent). No SQL Server support (unless using Laravel’s SQL Server driver).
• Customization Limits:
  • Actions: Can extend ArchiveAction but must use Filament’s action system.
  • Filters: ArchivedFilter is static; dynamic filters require subclassing.

Sequencing

1. Phase 1: Pilot with low-risk resources (e.g., logs, drafts) to validate UX and performance.
2. Phase 2: Roll out to core CRUD resources (e.g., users, orders) with archiving policies.
3. Phase 3: Integrate with workflows (e.g., archiving triggers cleanup jobs or notifications).
4. Phase 4: Optimize for scaling (e.g., adding DB indexes, caching filters).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor okeonline/filament-archivable and joelbutcher/laravel-archivable for breaking changes.
  • Upgrade Path: Minor updates are likely safe; major versions may require testing.
• Custom Code:
  • Extensions (e.g., custom actions) must be maintained alongside the plugin.
  • Risk: Plugin abandonment (low stars/downloads) could lead to unmaintained code. Mitigation: Fork if critical.
• Documentation:
  • Limited official docs; rely on README and GitHub issues. Recommendation: Create internal runbooks for:
    • Archiving policies (e.g., "Never archive active subscriptions").
    • Troubleshooting (e.g., "Filter not showing? Check archived_at column.").

Support

• Community:
  • Small community (20 stars, 0 dependents). Support channels: GitHub issues (response time ~days).
  • Workaround: Engage with Filament Discord or Laravel communities.
• Debugging:
  • Common Issues:
    • Actions not appearing: Check Filament resource permissions or plugin registration.
    • Filters not working: Verify archived_at column exists and is nullable.
  • Logging: Add debug logs for custom logic (e.g., archive callbacks).

Scaling

• Performance:
  • Filters: archived_at queries should be indexed:

    Schema::table('models', function (Blueprint $table) {
        $table->index('archived_at');
    });
    

  • Bulk Operations: Avoid bulk archiving/unarchiving on large tables (>100K records) without batching.
  • Caching: Filament table filters may benefit from query caching for frequent archived/unarchived toggles.
• Data Growth:
  • Storage: Archived records consume space. Plan for retention policies (e.g., purge after 2 years).
  • Backups: Ensure archived data is included in backups (default Laravel backups exclude deleted_at; confirm archived_at behavior).

Failure Modes

**Ramp