Revive Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require promethys/revive
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="Promethys\Revive\ReviveServiceProvider"
   php artisan migrate
   

2. Register the Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Promethys\Revive\RevivePlugin::make(),
           ]);
   }
   

3. First Use Case:

   • Soft-delete a model (e.g., User::find(1)->delete()).
   • Access the Recycle Bin via the Filament sidebar (default path: /admin/recycle-bin).
   • Restore or permanently delete the model from the UI.

Implementation Patterns

Core Workflows

1. Model Integration:

   • Soft-Deletes: Ensure your Eloquent models use SoftDeletes trait.
   • Scopes: Override the default query scope in config/revive.php:

     'query_scope' => \App\Models\Scopes\RecycleBinScope::class,
     

   • Custom Columns: Extend the table view via RevivePlugin::make():

     RevivePlugin::make()
         ->columns([
             Tables\Columns\TextColumn::make('custom_field'),
         ]),
     

2. Bulk Actions:

   • Leverage Filament’s built-in bulk actions (restore/delete) by default.
   • Customize via RevivePlugin::make()->actions([]).

3. Search & Filtering:

   • Use Filament’s native search or add custom filters:

     RevivePlugin::make()
         ->query(function (Builder $query) {
             return $query->where('deleted_at', '>', now()->subDays(7));
         }),
     

4. Permissions:

   • Restrict access via Filament’s canAccessRecycleBin policy:

     public function canAccessRecycleBin(): bool
     {
         return auth()->user()->isAdmin();
     }
     

5. Notifications:

   • Trigger events (ReviveEvents::MODEL_RESTORED) to send notifications:

     ReviveEvents::MODEL_RESTORED->listen(function ($model) {
         notify(new ModelRestored($model));
     });
     

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If deleted_at already exists in your models, the package’s migration will fail. Skip it or manually add the column:

     php artisan vendor:publish --tag="revive-migrations" --force
     

   • Then modify the migration to check for existing columns.

2. Query Scope Overrides:

   • The default scope (\Promethys\Revive\Scopes\RecycleBinScope) may conflict with existing scopes. Use withoutGlobalScopes() if needed:

     RevivePlugin::make()
         ->query(function (Builder $query) {
             return $query->withoutGlobalScopes()->whereMorph('model_type', [User::class]);
         }),
     

3. Performance:

   • Avoid loading large datasets. Use pagination or lazy-loading:

     RevivePlugin::make()
         ->perPage(20),
     

4. Soft-Deletes Timestamps:

   • Ensure deleted_at is nullable and indexed in your database:

     $table->timestamp('deleted_at')->nullable()->index();
     

Debugging

• Log Queries: Enable Filament’s query logging in config/filament.php:

  'debug' => env('FILAMENT_DEBUG', true),
  

• Check Events: Verify events are firing with:

  php artisan event:listen ReviveEvents::MODEL_RESTORED
  

Extension Points

1. Custom Actions:

   • Add a "Preview" action before restoring:

     RevivePlugin::make()
         ->actions([
             Tables\Actions\Action::make('preview')
                 ->url(fn ($record) => route('admin.models.preview', $record))
                 ->icon('heroicon-o-eye'),
         ]),
     

2. Dynamic Models:

   • Register models dynamically via a service provider:

     ReviveServiceProvider::macro('registerModels', function (array $models) {
         $this->app->make(\Promethys\Revive\ReviveServiceProvider::class)->registerModels($models);
     });
     

3. Localization:

   • Override translations in resources/lang/vendor/revive:

     'restore' => 'Recuperar',
     

4. Testing:

   • Use the ReviveTestCase trait for testing:

     use Promethys\Revive\Testing\ReviveTestCase;
     
     class RecycleBinTest extends ReviveTestCase
     {
         // ...
     }