Versionable Laravel Package

Technical Evaluation

Architecture Fit

• Versioning Paradigm: Aligns with soft versioning (delta-based) rather than hard snapshots, reducing storage overhead while preserving change history. Ideal for collaborative editing (e.g., CMS, CRM) where granularity matters.
• Polymorphic Users: Solves multi-guard/auth-system pain points (e.g., Admin, Client, Vendor users) by leveraging Laravel’s morphTo without manual foreign key management. Critical for SaaS/multi-tenant apps.
• Trait-Based: Zero base-class modifications required, enabling selective adoption (e.g., version only Post but not User). Low intrusion risk.
• Diff Integration: jfcherng/php-diff adds visual change tracking (HTML/JSON/text), justifying use in compliance-heavy domains (e.g., healthcare, finance).
• Event-Driven: Hooks into Eloquent’s saving/updating events, which may conflict with other event-based packages (e.g., spatie/laravel-activitylog).

Integration Feasibility

• Laravel 9+ Requirement: Blocks integration with Laravel <9 projects without major upgrades. PHP 8.1+ is standard for new dev but may be a hurdle for legacy systems.
• Database Schema: Single versions table with polymorphic user_id/user_type. Migration is automated but requires downtime if applied to production.
• Dependency Conflicts:
  • Event Collisions: Other packages using saving/updating events (e.g., spatie/laravel-activitylog) may interfere. Mitigate via event priority or conditional hooks.
  • Auth System: Assumes auth()->user() returns a model with morphMany support. Custom auth? Verify compatibility.
• Customization:
  • Version Strategies: DIFF (default) vs. SNAPSHOT tradeoffs (storage vs. fidelity).
  • Attribute Control: Per-model whitelists/blacklists reduce noise.
  • Custom Models: Extend \Visualbuilder\Versionable\Version for schema tweaks.

Key Questions

1. Auth System Compatibility:
   • Does your app use non-standard user models (e.g., User extends a custom base class)?
   • Are you using multiple guards (e.g., Sanctum + Passport)? Test polymorphic resolution.
2. Performance:
   • How many versioned models will you track? Bulk operations (e.g., removeAllVersions) could be slow for millions of records.
   • Will diff() operations impact response times in admin panels?
3. Storage Growth:
   • With DIFF strategy, storage scales with changes, not snapshots. Estimate growth for high-frequency updates.
4. Conflict Resolution:
   • How will you handle concurrent edits (e.g., two admins updating the same record)? Consider optimistic locking ($versionable->lockForUpdate()).
5. Rollback Safety:
   • Does your app need transactional reverts (e.g., fail if revert conflicts with DB constraints)?
6. Testing:
   • No CI badge or tests in README. Verify test coverage for your use case (e.g., polymorphic users, diff rendering).
7. Alternatives:
   • Compare with spatie/laravel-activitylog (more features, higher maintenance) or overtrue/laravel-versionable (original, no polymorphic users).

Integration Approach

Stack Fit

• Laravel 9+: Core requirement. If using Laravel 8, consider downgrading or forking.
• PHP 8.1+: Features like named arguments or union types may be used internally. Test with your stack.
• Eloquent Models: Only versionable models need the Versionable trait. Non-Eloquent models (e.g., API resources) are unsupported.
• Auth Systems:
  • Sanctum/Passport: Works out-of-the-box (polymorphic users).
  • Custom Guards: Ensure auth()->user() returns a model with morphMany support.
• Database:
  • MySQL/PostgreSQL: Test polymorphic joins (e.g., versions.user_id + versions.user_type).
  • SQLite: May need adjustments for polymorphic foreign keys.

Migration Path

1. Pre-Integration:
   • Audit event listeners for conflicts (e.g., saving/updating).
   • Backup existing data if versioning critical models.
2. Installation:

   composer require visualbuilder/versionable
   php artisan vendor:publish --provider="Visualbuilder\Versionable\ServiceProvider"
   php artisan migrate
   

3. Model Adoption:
   • Add use Visualbuilder\Versionable\Versionable; to target models.
   • Configure $versionable (whitelist) or $dontVersionable (blacklist).
   • Example:

     class Post extends Model {
         use Versionable;
         protected $versionable = ['title', 'content'];
         protected $versionStrategy = VersionStrategy::DIFF; // Optional
     }
     

4. Testing:
   • Verify polymorphic users work across guards (e.g., Admin vs. Client).
   • Test diff rendering in your frontend (e.g., Filament admin panel).
   • Validate revert operations don’t break transactions.

Compatibility

• With Other Packages:
  • Filament: Use mansoorkhan96/filament-versionable for UI integration.
  • Activity Log: Avoid mixing with spatie/laravel-activitylog (duplicate versioning).
  • Soft Deletes: Works with SoftDeletes trait (versions are soft-deleted too).
• Customization:
  • Version Model: Extend \Visualbuilder\Versionable\Version for custom fields (e.g., ip_address).
  • Events: Override bootVersionable() to add pre/post hooks.

Sequencing

1. Pilot Phase:
   • Start with non-critical models (e.g., BlogPost).
   • Test edge cases: rapid updates, polymorphic users, diff rendering.
2. Core Models:
   • Roll out to high-impact models (e.g., Customer, Product) after validation.
3. UI Integration:
   • Build admin views for version browsing/reverting (e.g., Filament tables).
4. Monitoring:
   • Track database growth (versions table).
   • Log revert failures (e.g., constraint violations).

Operational Impact

Maintenance

• Package Updates:
  • Monitor GitHub issues (0 stars = untested in production).
  • Fork if critical bugs arise (e.g., polymorphic user resolution).
• Schema Changes:
  • Future migrations may require manual intervention (e.g., adding columns to versions).
• Dependency Risks:
  • Relies on jfcherng/php-diff (external). Pin versions to avoid breaking changes.

Support

• Debugging:
  • Polymorphic User Issues: Use dd($version->user) to inspect relationships.
  • Diff Problems: Validate input data for diff() (e.g., non-serializable objects).
• Common Pitfalls:
  • Missing Auth: auth()->user() must return a model. Use optional(auth()->user()) to avoid errors.
  • Attribute Changes: Ensure $versionable includes all mutable fields.
• Documentation Gaps:
  • No examples for custom version models or event overrides. Fill gaps with internal docs.

Scaling

• Performance:
  • Bulk Operations: removeAllVersions() could lock tables. Use chunking:

    $post->versions()->cursor()->each(function ($version) {
        $version->delete();
    });
    

  • Diff Generation: Offload to queues for large models:

    $diff = $post->getVersion(1)->diff($post->getVersion(2)); // Heavy!
    

• Storage:
  • DIFF Strategy: Stores only changes (scalable for high-frequency updates).
  • SNAPSHOT Strategy: Stores full copies (risk of bloat). Monitor table size.
• Database Indexes:
  • Add indexes to versions(model_id, created_at) for query performance:

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

Failure Modes