Filament Versionable Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require visualbuilder/filament-versionable
   

2. Publish migrations and config:

   php artisan vendor:publish --provider="Visualbuilder\Versionable\ServiceProvider"
   php artisan migrate
   

3. Enable a custom Filament theme (required):
   • Follow Filament’s theme docs.
   • Add this to your theme CSS:

     @import '../../../../vendor/visualbuilder/filament-versionable/resources/css/plugin.css';
     @source '../../../../vendor/visualbuilder/filament-versionable/resources/**/*.blade.php';
     

First Use Case

Make a model versionable:

use Visualbuilder\Versionable\Versionable;
use Visualbuilder\Versionable\VersionStrategy;

class Post extends Model
{
    use Versionable;

    protected $versionable = ['title', 'content'];
    protected $versionStrategy = VersionStrategy::SNAPSHOT; // Recommended
}

Implementation Patterns

Core Workflow

1. Model Integration:

   • Add Versionable trait to Eloquent models.
   • Define $versionable (attributes to track) and $versionStrategy (use SNAPSHOT for reliability).
   • Example:

     class Article extends Model
     {
         use Versionable;
     
         protected $versionable = ['slug', 'body'];
         protected $versionStrategy = VersionStrategy::SNAPSHOT;
     }
     

2. Filament Resource Setup:

   • Create a RevisionsPage for your resource:

     namespace App\Filament\Resources\ArticleResource\Pages;
     
     use App\Filament\Resources\ArticleResource;
     use Visualbuilder\FilamentVersionable\RevisionsPage;
     
     class ArticleRevisions extends RevisionsPage
     {
         protected static string $resource = ArticleResource::class;
     }
     

   • Register the page in your resource:

     public static function getPages(): array
     {
         return [
             'revisions' => Pages\ArticleRevisions::route('/{record}/revisions'),
         ];
     }
     

3. UI Integration:

   • Add RevisionsAction to edit/view pages:

     use Visualbuilder\FilamentVersionable\Page\RevisionsAction;
     
     protected function getHeaderActions(): array
     {
         return [
             RevisionsAction::make(),
         ];
     }
     

   • Add RevisionsAction to tables:

     use Visualbuilder\FilamentVersionable\Table\RevisionsAction;
     
     $table->actions([
         RevisionsAction::make(),
     ]);
     

Advanced Patterns

• Polymorphic Users: Works out-of-the-box with visualbuilder/versionable’s polymorphic support (e.g., User, Admin, OrganisationUser).
• Diff Customization: Override shouldStripTags() in RevisionsPage for HTML content:

  public function shouldStripTags(): bool
  {
      return true;
  }
  

• Bulk Restore: Use the RevisionsPage to restore any version via the UI.

Gotchas and Tips

Pitfalls

1. Version Strategy:

   • Avoid DIFF: The README warns of bugs with VersionStrategy::DIFF. Use SNAPSHOT for reliability.
   • Snapshot Overhead: SNAPSHOT stores full attribute copies, which may bloat storage for large models.

2. Filament Theme Requirement:

   • Critical: Forgetting to add the CSS/Blade imports will break the UI. Always verify:

     @import '../../../../vendor/visualbuilder/filament-versionable/resources/css/plugin.css';
     @source '../../../../vendor/visualbuilder/filament-versionable/resources/**/*.blade.php';
     

3. Polymorphic User Edge Cases:

   • Null Users: Handle cases where $versionable['user_id'] or $versionable['user_type'] might be null (e.g., in tests or migrations).

4. Migration Conflicts:

   • If you’ve used overtrue/laravel-versionable before, drop its migrations first to avoid conflicts:

     php artisan migrate:fresh --env=testing
     

Debugging Tips

• Check Version Storage: Inspect the versions table directly to verify data:

  \DB::table('versions')->where('versionable_id', $model->id)->get();
  

• Diff Issues: If diffs appear empty, ensure:
  • $versionable attributes are correctly defined.
  • The shouldStripTags() method isn’t interfering (toggle it to test).

Extension Points

1. Custom Views: Publish views for overrides:

   php artisan vendor:publish --tag="filament-versionable-views"
   

   Then modify resources/views/vendor/filament-versionable/....

2. Versionable Attributes Dynamically: Use a getter to define $versionable dynamically:

   public function getVersionableAttributes(): array
   {
       return ['title', 'content'];
   }
   

3. Event Hooks: Listen to versioning events (via visualbuilder/versionable) for custom logic:

   \Visualbuilder\Versionable\Events\Versioning::class => [YourListener::class, 'handle'],
   

Performance

• Indexing: Add indexes to versions table for large datasets:

  Schema::table('versions', function (Blueprint $table) {
      $table->index(['versionable_id', 'versionable_type']);
  });
  

• Batch Processing: For bulk operations, disable versioning temporarily:

  $model->disableVersioning();
  // ... bulk operations ...
  $model->enableVersioning();