Laravel Versionable Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

2. Enable Versioning: Add the Versionable trait to your model and define $versionable attributes:

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

First Use Case

Automatically track changes to title and content fields:

$post = Post::create(['title' => 'Initial', 'content' => 'Draft']);
$post->update(['title' => 'Updated Title']); // Creates a new version

Implementation Patterns

Core Workflows

1. Version Retrieval:

   // Get all versions
   $versions = $post->versions;
   
   // Get latest version
   $latest = $post->latestVersion;
   
   // Get version by ID
   $version = $post->getVersion(3);
   

2. Reversion:

   // Revert to version 2
   $post->revertToVersion(2);
   
   // Or via version object
   $post->getVersion(2)->revert();
   

3. Diffing:

   $diff = $post->getVersion(1)->diff($post->getVersion(2));
   $diff->toHtml(); // Render as HTML
   

Advanced Patterns

1. Temporary Disabling:

   Post::withoutVersion(function () {
       Post::create(['title' => 'No Version']);
   });
   

2. Custom Version Model:

   class PostVersion extends \Overtrue\LaravelVersionable\Version {}
   class Post extends Model {
       use Versionable;
       public string $versionModel = PostVersion::class;
   }
   

3. Version Strategies:

   class Post extends Model {
       use Versionable;
       protected $versionStrategy = VersionStrategy::SNAPSHOT; // Full snapshot
   }
   

Integration Tips

• Filament Admin: Use mansoorkhan96/filament-versionable for UI management.
• API Responses: Serialize versions with $post->versions->load('model').
• Testing: Mock version creation with Post::withoutVersion() in tests.

Gotchas and Tips

Common Pitfalls

1. Performance:

   • Avoid eager-loading versions unless needed ($post->load('versions')).
   • Use withoutVersion() for bulk operations to skip versioning.

2. Diff Strategy:

   • DIFF (default) only stores changed attributes, but may miss context.
   • SNAPSHOT stores full copies, useful for complex data.

3. Soft Deletes:

   • Use forceRemoveVersion() to permanently delete versions.
   • Restore with restoreTrashedVersion($id).

Debugging Tips

1. Version Not Created?

   • Check $versionable attributes are whitelisted.
   • Verify no global scopes exclude the model.

2. Diff Issues:

   • Use $stripTags = true for HTML content.
   • For arrays, ensure consistent keys in versions.

3. Custom Model Errors:

   • Ensure your version model extends \Overtrue\LaravelVersionable\Version.

Extension Points

1. Custom Version Logic: Override createVersion() or shouldCreateVersion() in your model.

2. Version Storage: Extend the Version model to add custom fields (e.g., user_id).

3. Diff Formatting: Customize diff output by extending the Diff class or using php-diff options.

Configuration Quirks

• Database Connection: Ensure migrations run on the correct connection.
• Primary Key: Version model must use id as primary key by default.
• Timestamps: Version model uses created_at for version ordering.