Laravel Rewind Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require avocet-shores/laravel-rewind
   php artisan vendor:publish --provider="AvocetShores\LaravelRewind\LaravelRewindServiceProvider"
   php artisan migrate
   

2. Enable Versioning: Add the Rewindable trait to your Eloquent model:

   use AvocetShores\LaravelRewind\Traits\Rewindable;
   
   class Post extends Model {
       use Rewindable;
   }
   

3. Add Version Column:

   php artisan rewind:add-version
   php artisan migrate
   

First Use Case

Track and Rewind Changes:

$post = Post::find(1);
$post->update(['title' => 'Updated Title']);
Rewind::rewind($post); // Revert to previous version

Implementation Patterns

Core Workflows

1. Basic Version Navigation:

   Rewind::goTo($post, 3); // Jump to version 3
   Rewind::rewind($post);   // Move back 1 version
   Rewind::fastForward($post); // Move forward 1 version
   

2. State Restoration:

   Rewind::restore($post, 2); // Create new version from v2's state
   

3. Batch Versioning:

   Rewind::batch(function () {
       $order->update(['status' => 'shipped']);
       $item->update(['shipped_at' => now()]);
   });
   

Integration Tips

• Queue Version Creation (for high-traffic models):

  // config/rewind.php
  'listener_should_queue' => true,
  

• State Field Tracking:

  class Order extends Model {
      use Rewindable;
      protected array $rewindStateFields = ['status', 'payment_status'];
  }
  

• Exclude Sensitive Fields:

  public static function excludedFromVersioning(): array {
      return ['password', 'api_token'];
  }
  

Common Use Cases

• Audit Logs: Query version history with scopes:

  $post->versions()->whereStateBecame('status', 'published')->get();
  

• Time-Travel Queries:

  $oldAttributes = Rewind::versionAt($post, Carbon::yesterday());
  

• Diff Analysis:

  $diff = Rewind::diff($post, 1, 5);
  if ($diff->changed) {
      // Handle changes
  }
  

Gotchas and Tips

Pitfalls

1. Lock Timeouts:

   • Concurrent writes may cause LockTimeoutRewindException. Configure handling in config/rewind.php:

     'on_lock_timeout' => 'event', // Options: 'log', 'event', 'throw'
     

2. Snapshot Interval:

   • Too high (snapshot_interval) = slower reconstruction.
   • Too low = increased storage usage.

3. Amend vs. Exclude:

   • Use amendCurrentVersion() for fields you want sometimes tracked.
   • Use excludedFromVersioning() for fields never to track.

Debugging

• Check Version Reconstruction:

  $attributes = Rewind::getVersionAttributes($post, 7);
  // Debug missing fields if diffs are incomplete
  

• Batch UUID Mismatch:

  • Ensure all models in a batch are saved before committing the batch UUID.

Extension Points

1. Custom Version Model: Extend RewindVersion to add columns/scopes:

   // config/rewind.php
   'version_model' => App\Models\CustomRewindVersion::class,
   

2. Event Listeners: Listen for RewindVersionLockTimeout or RewindVersionCreated events.

3. Pruning Logic: Override prune() in your custom version model for custom cleanup rules.

Performance Tips

• Snapshot Interval Tuning: Monitor rewind_versions table size vs. query performance to adjust snapshot_interval.

• Queued Versioning: For bulk operations, use Rewind::batch() to group versions and reduce lock contention.

Quirks

• State Transitions:

  • Transitions are collapsed in amendCurrentVersion() mode. Use initVersion() for baseline snapshots.

• Pruning Behavior:

  • Pruning converts the new oldest version into a snapshot automatically. Test with --pretend first.

• Diff Directionality: Rewind::diff($model, 5, 1) reverses old/new values. Use ->isEmpty() to verify.