Filament Versionable Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: Seamlessly integrates with Filament v4/v5, leveraging its resource-based architecture for versioning UI. The package extends Filament’s built-in resource pages (RevisionsPage) and actions (RevisionsAction), ensuring consistency with the admin panel’s design system.
• Underlying Versioning: Built atop Laravel Versionable (v5+), which provides robust model versioning via snapshot or diff strategies. The package abstracts version storage logic, allowing TPMs to focus on UI/UX without deep ORM concerns.
• Modularity: Lightweight (~100 stars, MIT license) with clear separation of concerns—versioning logic (Laravel Versionable) and Filament-specific UI (this package). Ideal for projects already using Filament or Laravel Versionable.

Integration Feasibility

• Prerequisites:
  • Filament v4/v5: Required for UI components (e.g., RevisionsPage). Compatibility with Filament v3 is unsupported (per changelog).
  • Laravel Versionable: Core dependency for versioning logic. Must be installed separately (composer require overtrue/laravel-versionable).
  • Custom Filament Theme: Mandatory for CSS/Blade integration (per README). Projects without a custom theme will need to create one.
• Database Schema: Publishes migrations for version tables (versions). Requires php artisan migrate post-installation.
• Model-Level Setup: Minimal boilerplate—add the Versionable trait and $versionable array to Eloquent models. Snapshot strategy recommended (diff strategy has known bugs per README).

Technical Risk

• Version Strategy Pitfalls:
  • Snapshot vs. Diff: Snapshot stores full copies of versioned attributes (safe but storage-intensive). Diff tracks changes (efficient but risk of data loss if corrupted; see Laravel Versionable docs).
  • UUID Support: Recent fix (v4.0) addresses showVersion breaking with UUIDs, but edge cases may persist for non-integer IDs.
• Filament Version Lock-in:
  • Tied to Filament v4/v5. Upgrades may require package updates (e.g., v5.0 added Filament v5 support).
  • Custom theme requirement adds friction for projects without existing themes.
• Performance:
  • Version storage scales with model updates. Large datasets may impact query performance (e.g., versions table joins).
  • No built-in pagination for revisions lists (relies on Filament’s default pagination).

Key Questions

1. Versioning Granularity:
   • Should all model attributes be versioned, or only specific fields? (Affects $versionable array and storage costs.)
   • Is snapshot or diff strategy preferred? (Trade-offs: safety vs. storage.)
2. Filament Compatibility:
   • Is the project using Filament v4 or v5? (Package supports both, but v5 may have subtle differences.)
   • Does the project have a custom Filament theme? If not, theme creation will be a blocking task.
3. Database Considerations:
   • What’s the expected volume of revisions? (May require indexing or archiving strategies for large datasets.)
   • Are there existing versioning systems (e.g., Git, custom logs) that could conflict?
4. UI/UX Requirements:
   • Should revisions support HTML stripping (e.g., for content fields)? (Configurable via shouldStripTags().)
   • Are there localization needs beyond English? (Package supports translations but may lack for niche languages.)
5. Rollback Workflow:
   • How often will users restore versions? (Affects UI placement of RevisionsAction.)
   • Should restores be audit-logged or trigger notifications? (Not natively supported.)

Integration Approach

Stack Fit

• Primary Use Case: Ideal for Filament-powered admin panels managing content with revision history needs (e.g., CMS, CRM, or SaaS platforms).
• Tech Stack Synergy:
  • Laravel: Native Eloquent model support; minimal ORM overhead.
  • Filament: Leverages existing resource pages/actions for zero-context-switching.
  • PHP 8.1+: Required by Laravel Versionable v5 (check project compatibility).
• Alternatives Considered:
  • Manual Versioning: Higher dev effort (e.g., custom middleware + database triggers).
  • Third-Party Packages: Few Filament-specific options exist; this package is the most mature.
  • Laravel Versionable Alone: Lacks Filament UI integration (requires custom frontend work).

Migration Path

1. Prerequisite Setup:
   • Upgrade to Filament v4/v5 (if not already).
   • Create a custom Filament theme (if none exists):

     php artisan make:filament-theme custom
     

   • Add theme CSS/Blade imports (per README):

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

2. Installation:

   composer require mansoor/filament-versionable overtrue/laravel-versionable
   php artisan vendor:publish --provider="Overtrue\LaravelVersionable\ServiceProvider"
   php artisan migrate
   

3. Model Integration:
   • Add Versionable trait and configure $versionable:

     use Overtrue\LaravelVersionable\Versionable;
     
     class Post extends Model {
         use Versionable;
         protected $versionable = ['title', 'content'];
         protected $versionStrategy = VersionStrategy::SNAPSHOT;
     }
     

4. Filament Resource Setup:
   • Extend RevisionsPage for each resource:

     namespace App\Filament\Resources\PostResource\Pages;
     use Mansoor\FilamentVersionable\RevisionsPage;
     
     class PostRevisions extends RevisionsPage {
         protected static string $resource = PostResource::class;
     }
     

   • Register the page in getPages():

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

5. UI Integration:
   • Add RevisionsAction to edit/view pages or tables:

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

Compatibility

• Filament Versions: Officially supports v4/v5. Test for v6+ if upgrading.
• Laravel Versions: Compatible with Laravel 10/11/12 (per changelog). Avoid older versions due to Laravel Versionable constraints.
• Database: MySQL/PostgreSQL/SQLite (standard Laravel support). No vendor-specific features.
• Dependencies:
  • Filament: Core dependency (no alternatives).
  • Laravel Versionable: Critical for versioning logic (no drop-in replacements).

Sequencing

1. Phase 1: Foundation (1–2 days):
   • Set up Filament theme and publish migrations.
   • Integrate Laravel Versionable and test basic versioning.
2. Phase 2: Model Integration (1 day per critical model):
   • Apply Versionable trait to key models (e.g., Post, UserProfile).
   • Validate snapshot/diff behavior.
3. Phase 3: UI Rollout (1–3 days):
   • Add RevisionsPage and RevisionsAction to resources.
   • Customize UI (e.g., translations, HTML stripping).
4. Phase 4: Testing & Optimization (1 week):
   • Load-test version storage (simulate high-update models).
   • Monitor database performance (index versions table if needed).
   • Gather feedback on restore workflows.

Operational Impact

Maintenance

• Package Updates:
  • Monitor mansoor/filament-versionable and overtrue/laravel-versionable for breaking changes (e.g., Filament v5+ updates).
  • Dependency updates may require testing (e.g., Laravel 13 support added in v5.1).
• Customizations:
  • Published views allow UI overrides (e.g., php artisan vendor:publish --tag="filament-versionable-views").
  • Core logic (e.g., version storage) is abstracted; modifications require Laravel Versionable tweaks.
• Backup Strategy:
  • versions table grows with usage. Consider:
    • Archiving: Move old versions to cold storage (e.g., separate DB or S3).
    • Retention Policies: Soft-delete or purge versions after X days (custom logic).

Support

• Troubleshooting:
  • Common Issues:
    • Missing revisions: Verify $versionable attributes and VersionStrategy.