Revive Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require promethys/revive
   php artisan revive:install
   

   Ensure you're using Laravel 11+, Filament v5, and PHP 8.2+.

2. Register the Plugin: Add to your Filament panel configuration:

   use Promethys\Revive\RevivePlugin;
   
   $panel->plugins([
       RevivePlugin::make(),
   ]);
   

3. Enable Recycling for Models: Add the Recyclable trait to any soft-deletable model:

   use Promethys\Revive\Concerns\Recyclable;
   
   class Post extends Model
   {
       use SoftDeletes;
       use Recyclable;
   }
   

4. Access the Recycle Bin: Navigate to the new "Recycle Bin" entry in your Filament sidebar.

Implementation Patterns

Core Workflow

1. Deletion:

   • Soft-delete records normally ($post->delete()).
   • Revive automatically tracks deletions in its database table (revive_records).

2. Restoration:

   • Use the Filament UI to restore records via the "Restore" action.
   • Revive handles the restore() call and cleans up its tracking.

3. Permanent Deletion:

   • Use the "Delete Forever" action to force-delete records.
   • Revive removes the record from its tracking table.

Integration Patterns

Model Registration

• Bulk Registration: Register multiple models at once:

  RevivePlugin::make()
      ->models([Post::class, Comment::class])
  

• Dynamic Registration: Use a service provider to register models dynamically:

  public function boot()
  {
      $models = Model::where('is_recyclable', true)->get()->pluck('class');
      $this->app->make(RevivePlugin::class)->models($models);
  }
  

Scoping Strategies

• User-Scoped: Default behavior for user panels:

  RevivePlugin::make()
      ->enableUserScoping()
  

• Tenant-Scoped: For multi-tenant applications:

  RevivePlugin::make()
      ->enableTenantScoping()
  

• Admin-Scoped: Show all records for admins:

  RevivePlugin::make()
      ->showAllRecords()
      ->authorize(fn () => auth()->user()->isAdmin())
  

Custom UI Integration

• Embed in Custom Pages:

  @livewire(\Promethys\Revive\Tables\RecycleBin::class, [
      'models' => [App\Models\Post::class],
      'user' => auth()->user(),
  ])
  

• Override Table Behavior: Extend the base table class:

  class CustomRecycleBin extends \Promethys\Revive\Tables\RecycleBin
  {
      protected function getTableColumns(): array
      {
          return [
              ...parent::getTableColumns(),
              TextColumn::make('custom_field'),
          ];
      }
  }
  

CLI Workflow

• Discover Existing Records:

  php artisan revive:discover-soft-deleted --with-scope
  

  Run this after upgrading or when migrating existing soft-deleted records.

Gotchas and Tips

Common Pitfalls

1. Missing SoftDeletes Trait:

   • Error: Recyclable trait requires SoftDeletes.
   • Fix: Ensure your model uses both traits:

     use Illuminate\Database\Eloquent\SoftDeletes;
     use Promethys\Revive\Concerns\Recyclable;
     
     class Post extends Model
     {
         use SoftDeletes, Recyclable;
     }
     

2. Namespace Restrictions:

   • Issue: Revive only tracks models in the App\Models namespace by default.
   • Fix: Wrap third-party models:

     namespace App\Models;
     
     use Promethys\Revive\Concerns\Recyclable;
     use Vendor\Package\Models\ThirdPartyModel;
     
     class ThirdPartyModelWrapper extends ThirdPartyModel
     {
         use SoftDeletes, Recyclable;
     }
     

3. Scoping Conflicts:

   • Issue: Mixed enableUserScoping and enableTenantScoping can cause unexpected behavior.
   • Fix: Explicitly disable one if not needed:

     RevivePlugin::make()
         ->enableUserScoping()
         ->enableTenantScoping(false)
     

4. State Snapshots:

   • Gotcha: Revive stores a snapshot of the model's state at deletion time. If your model has computed properties or accessors, these may not be preserved.
   • Tip: Use getAttributes() or explicitly define snapshot fields:

     protected static function getReviveSnapshotAttributes(): array
     {
         return ['title', 'content', 'published_at'];
     }
     

Debugging Tips

1. Check Tracking: Verify records are being tracked in the revive_records table:

   php artisan tinker
   >>> \Promethys\Revive\Models\ReviveRecord::all();
   

2. Log Deletions: Enable logging for debugging:

   RevivePlugin::make()
       ->logDeletions(true);
   

3. CLI Dry Runs: Test the discovery command without changes:

   php artisan revive:discover-soft-deleted --dry-run
   

Performance Considerations

1. Large Datasets:

   • Revive uses eager loading for related models. For large datasets, consider adding indexes to the revive_records table:

     Schema::table('revive_records', function (Blueprint $table) {
         $table->index('model_type');
         $table->index('model_id');
     });
     

2. Snapshot Storage:

   • Snapshots are stored as JSON. For models with large attributes, limit snapshot fields to essential data.

Extension Points

1. Custom Actions: Extend the table to add custom actions:

   protected function getTableRecordActions(): array
   {
       return [
           ...parent::getTableRecordActions(),
           Action::make('customAction')
               ->action(function (ReviveRecord $record) {
                   // Custom logic
               }),
       ];
   }
   

2. Override Restoration Logic: Hook into the restoration process:

   use Promethys\Revive\Events\RecordRestored;
   
   Event::listen(RecordRestored::class, function ($event) {
       // Post-restore logic
   });
   

3. Custom Scoping: Override the default scoping logic in your model:

   class Post extends Model
   {
       use Recyclable;
   
       public function scopeCustomScoping($query)
       {
           return $query->where('is_active', true);
       }
   }