Filament Archivable Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require okeonline/filament-archivable
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Okeonline\FilamentArchivable\FilamentArchivableServiceProvider"
   

2. Enable for a Resource Add the trait to your resource class:

   use Okeonline\FilamentArchivable\Concerns\HasArchivableActions;
   use Okeonline\FilamentArchivable\Concerns\HasArchivableFilters;
   
   class YourResource extends Resource
   {
       use HasArchivableActions, HasArchivableFilters;
       // ...
   }
   

3. First Use Case

   • The plugin automatically adds:
     • Archive/Unarchive buttons in table actions.
     • Archived filter in the table header.
   • No model changes required if using joelbutcher/laravel-archivable.

Implementation Patterns

Core Workflows

1. Basic Usage

   // In your Resource class
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               // ...
           ])
           ->actions([
               ArchiveAction::make(),
               UnArchiveAction::make(),
           ])
           ->filters([
               ArchivedFilter::make(),
           ]);
   }
   

2. Customizing Actions

   • Icon/Label:

     ArchiveAction::make()
         ->icon('heroicon-o-archive')
         ->label('Move to Archive');
     

   • Authorization:

     ArchiveAction::make()
         ->requiresConfirmation()
         ->canOnlyArchiveWhen(fn ($record) => auth()->user()->can('archive', $record));
     

3. Filter Integration

   • Default Behavior: Shows only non-archived records.
   • Toggle via Filter:

     ArchivedFilter::make()
         ->label('Show Archived')
         ->default(false); // Start with non-archived
     

4. Bulk Actions

   • Enable bulk archive/unarchive:

     ArchiveAction::make()->bulk(),
     UnArchiveAction::make()->bulk(),
     

Advanced Patterns

1. Soft-Deletes + Archivable If your model uses SoftDeletes, ensure the archived_at column is distinct:

   use HasArchivableTrait;
   use SoftDeletes;
   
   class Model extends Model
   {
       use HasArchivableTrait, SoftDeletes;
   
       protected $dates = ['archived_at', 'deleted_at'];
   }
   

2. Custom Archive Logic Override the default behavior via the model:

   class Model extends Model
   {
       use HasArchivableTrait;
   
       public function archive(): void
       {
           $this->update(['archived_at' => now(), 'custom_status' => 'archived']);
       }
   }
   

3. Resource-Level Configuration Disable globally in config/filament-archivable.php:

   'default' => [
       'actions' => false,
       'filters' => false,
   ],
   

   Then enable per-resource:

   use HasArchivableActions;
   

Gotchas and Tips

Pitfalls

1. Missing archived_at Column

   • Error: Column not found: 1054 Unknown column 'archived_at'.
   • Fix: Run the migration from joelbutcher/laravel-archivable or add the column manually:

     php artisan vendor:publish --provider="JoelButcher\Archivable\ArchivableServiceProvider"
     php artisan migrate
     

2. Conflicts with SoftDeletes

   • Issue: If deleted_at and archived_at are both nullable, queries may behave unexpectedly.
   • Fix: Explicitly scope queries:

     public static function getArchivedQuery(): Builder
     {
         return parent::getArchivedQuery()->whereNull('deleted_at');
     }
     

3. Permission Denied

   • Symptom: Actions appear but fail silently.
   • Debug: Check canOnlyArchiveWhen or Filament’s built-in policies:

     ArchiveAction::make()->canOnlyArchiveWhen(fn ($record) => auth()->user()->can('archive', $record));
     

Debugging

1. Log Queries Enable Laravel query logging to inspect generated SQL:

   DB::enableQueryLog();
   // Trigger action/filter
   tap(DB::getQueryLog(), function ($logs) {
       dd($logs);
   });
   

2. Check Middleware Ensure joelbutcher/laravel-archivable middleware is registered:

   // app/Http/Kernel.php
   'archivable' => \JoelButcher\Archivable\Middleware\Archivable::class,
   

Extension Points

1. Custom Archive Fields Extend the trait to add custom logic:

   class Model extends Model
   {
       use HasArchivableTrait;
   
       protected static function booted(): void
       {
           static::archiving(function ($model) {
               $model->update(['backup_data' => $model->replicate()]);
           });
       }
   }
   

2. Override Filter Behavior Customize the ArchivedFilter:

   class CustomArchivedFilter extends ArchivedFilter
   {
       protected function setUp(): void
       {
           parent::setUp();
           $this->label('Custom Archive Status');
           $this->options([
               'active' => 'Active',
               'archived' => 'Archived',
               'all' => 'All',
           ]);
       }
   }
   

3. Localization Translate labels/actions:

   ArchiveAction::make()
       ->label(__('filament-archivable::actions.archive'))
       ->successNotificationMessage(__('filament-archivable::actions.archived'));
   

Performance Tips

1. Index archived_at Add an index to the column for faster filtering:

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

2. Batch Processing For bulk actions, use chunking to avoid memory issues:

   UnArchiveAction::make()
       ->bulk()
       ->action(function (Collection $records) {
           $records->each->restore();
           // OR chunked restore:
           $records->chunk(100)->each(function ($chunk) {
               $chunk->each->restore();
           });
       });