Eloquent Versioning Laravel Package

Technical Evaluation

Architecture Fit

• Versioning Use Case: The package provides a clean, Eloquent-based solution for tracking attribute-level revisions, which aligns well with audit-heavy applications (e.g., compliance, content management, or financial systems). It avoids manual versioning logic, reducing boilerplate.
• Separation of Concerns: Versioned data is stored in a dedicated table (versions), preserving the main model’s integrity while enabling historical queries.
• Soft Deletes & Timestamps: Supports versioning of soft deletes and timestamps, which is critical for applications requiring granular rollback or compliance tracking.

Integration Feasibility

• Laravel 5.x Compatibility: The package targets Laravel 5.x, which may require polyfills or adjustments for newer Laravel versions (e.g., 8/9/10). The last release (2018) suggests potential compatibility gaps with modern PHP/Laravel features (e.g., dependency injection, query builder changes).
• Database Schema: Requires manual migration setup (e.g., versions table, latest_version column). Schema design must account for:
  • Foreign key constraints between users and versions.
  • Indexing strategies for performance (e.g., versioned_at, model_id).
• Query Complexity: Retrieving historical data involves joins or subqueries, which could impact performance if not optimized (e.g., caching frequent version queries).

Technical Risk

• Abandoned Maintenance: No releases since 2018 raises risks:
  • Incompatibility with newer Laravel/PHP versions (e.g., array_column deprecations, Eloquent API changes).
  • Security vulnerabilities (e.g., SQL injection if not using Laravel’s query builder).
• Feature Gaps:
  • No built-in support for bulk operations (e.g., versioning during update() on multiple records).
  • Limited conflict resolution for concurrent updates (e.g., optimistic locking).
  • No native diffing or comparison tools between versions.
• Testing Overhead: Custom validation or business logic tied to versioning may require additional test coverage.

Key Questions

1. Laravel Version Compatibility:
   • What’s the target Laravel/PHP version for the project? Are polyfills or forks needed?
   • Has the package been tested with Laravel 8/9/10’s Eloquent changes (e.g., newQuery() vs. query())?
2. Performance:
   • How will version queries scale with high-frequency updates? Are read replicas or caching (e.g., Redis) viable?
   • What’s the expected size of the versions table? Are archiving strategies needed?
3. Alternatives:
   • Could Laravel’s built-in model events (updating) + a custom versions table achieve similar results with less risk?
   • Are there active alternatives (e.g., spatie/laravel-activitylog, laravel-model-versions)?
4. Data Integrity:
   • How will foreign key constraints be handled if versioned records are soft-deleted?
   • Is there a risk of orphaned version records if the main model is deleted?
5. Rollback/Undo:
   • Does the package support programmatic rollback to prior versions? If not, how will this be implemented?

Integration Approach

Stack Fit

• Laravel Ecosystem: Ideal for projects already using Eloquent, as it extends the ORM without requiring major architectural shifts.
• Database: Works with MySQL, PostgreSQL, SQLite (via Eloquent). No vendor-specific features.
• PHP Version: Requires PHP 5.6+ (Laravel 5.x). May need updates for PHP 8.x (e.g., named arguments, JIT).
• Tooling: Composer-based installation simplifies dependency management.

Migration Path

1. Assessment Phase:
   • Audit existing models to identify versioning candidates (e.g., User::email, Product::price).
   • Benchmark performance of versioned queries against non-versioned equivalents.
2. Schema Migration:
   • Add latest_version column to target tables (e.g., users).
   • Create versions table with columns:

     Schema::create('versions', function (Blueprint $table) {
         $table->id();
         $table->string('model_type'); // e.g., "App\Models\User"
         $table->unsignedBigInteger('model_id');
         $table->json('changes'); // or serialized array for older PHP
         $table->timestamps();
         $table->softDeletes();
         $table->foreign('model_id')->references('id')->on('users')->onDelete('cascade');
     });
     

   • Consider adding indexes on (model_type, model_id, versioned_at).
3. Model Integration:
   • Use the package’s trait (Versionable) and configure versioned attributes:

     use ProAI\EloquentVersioning\Versionable;
     
     class User extends Model {
         use Versionable;
     
         protected $versioned = ['email', 'city'];
         protected $versionedTimestamps = true;
         protected $versionedSoftDeletes = true;
     }
     

4. Testing:
   • Validate version creation on updates:

     $user = User::find(1);
     $user->email = 'new@example.com';
     $user->save(); // Triggers versioning.
     

   • Test historical queries:

     $versions = $user->versions()->orderBy('created_at', 'desc')->get();
     

Compatibility

• Laravel Services: May conflict with:
  • Observers/Events: Versioning occurs during updating, which could interfere with custom event logic.
  • Scopes: Versioned queries may need custom scopes (e.g., scopeWithVersion($query, $version)).
• Third-Party Packages:
  • Check for conflicts with packages using Eloquent macros or model events (e.g., laravel-medialibrary).
  • Ensure compatibility with packages modifying save() (e.g., laravel-activitylog).

Sequencing

1. Pilot Phase:
   • Start with a non-critical model (e.g., BlogPost) to test versioning behavior.
   • Monitor database growth and query performance.
2. Incremental Rollout:
   • Version high-impact models first (e.g., User, Order).
   • Gradually add versioned attributes to reduce risk.
3. Post-Launch:
   • Implement monitoring for version table bloat.
   • Develop rollback/undo functionality if not natively supported.

Operational Impact

Maintenance

• Dependency Risks:
  • Forking may be necessary for Laravel 8+ compatibility. Maintain a local branch for fixes.
  • Monitor for upstream security patches (though unlikely given inactivity).
• Schema Changes:
  • Future migrations must account for versioned data (e.g., renaming columns, adding constraints).
  • Consider a versions table naming convention (e.g., user_versions) for clarity.
• Documentation:
  • Internal docs should outline:
    • How to query versions (e.g., user->versions->where('changes->email', 'old@example.com')).
    • Rollback procedures (if manual).
    • Performance tuning (e.g., indexing, archiving).

Support

• Debugging:
  • Versioning logic may obscure traditional debugging (e.g., "Why did this save fail?" → Check versions table).
  • Add logging for version creation events:

    $user->save(); // Logs to `versions` but also to a monitoring tool.
    

• User Training:
  • Educate developers on:
    • When to use versioning (e.g., mutable fields like email vs. immutable id).
    • How to write queries for historical data.
  • Provide examples for common use cases (e.g., "Show me all changes to this user’s email").

Scaling

• Database Load:
  • Versioning adds overhead to save() operations. Benchmark with production-like data volumes.
  • Consider partitioning the versions table by model_type or created_at for large datasets.
• Read Performance:
  • Cache frequent version queries (e.g., "Show last 5 versions of this record") using Redis.
  • Use materialized views or denormalized tables for common historical reports.
• Archiving:
  • Implement a cron job to archive old versions (e.g., move to versions_archive after 2 years).
  • Example:

    DB::table('versions')
      ->where('created_at', '<', now()->subYears(2))
      ->update(['archived' => true]);
    

Failure Modes