grazulex/laravel-draftable

Add drafts, versioning, and publication workflow to any Eloquent model โ€” ideal for content editing, previews, and rollback.

v1.0.0 2025-08-08 03:28 UTC

This package is auto-updated.

Last update: 2025-08-08 03:57:11 UTC


README

Laravel Draftable

Production-ready drafts, versioning, and publication flow for any Eloquent model

A comprehensive package for managing content lifecycle with enterprise-grade quality

Latest Version Total Downloads License PHP Version Laravel Version Tests Coverage Code Style Static Analysis

๐Ÿš€ Overview

Laravel Draftable is a production-ready package that adds comprehensive drafts, versioning, and publication workflows to any Eloquent model in Laravel. Perfect for content management systems, blog platforms, documentation sites, e-commerce products, and any application where you need reliable content lifecycle management with version control capabilities.

โœจ Key Features

  • ๐Ÿ“ Draft System - Save changes without publishing immediately
  • ๐Ÿ•’ Version History - Complete tracking of all changes over time
  • ๐Ÿ” Version Comparison - Detailed diff analysis between any versions
  • โช Version Restoration - Restore to any previous version instantly
  • ๐Ÿš€ Flexible Publishing - Manual or automatic publication workflows
  • ๐Ÿ—„๏ธ Storage Strategies - Same table or separate drafts table support
  • ๐Ÿ‘๏ธ Draft Preview - Preview changes without making them live
  • ๐Ÿ”’ Access Control - Full Laravel policies integration
  • ๐Ÿ“Š Performance Optimized - Optimized database queries and indexes
  • ๐ŸŽจ Artisan Commands - Complete CLI management suite
  • ๐Ÿงช Test Coverage - 128/128 tests passing with 93.6% coverage
  • โšก Events System - Laravel events for draft lifecycle
  • ๐Ÿ›ก๏ธ Production Ready - Zero static analysis errors (PHPStan level 5)

๏ฟฝ Installation

Install the package via Composer:

composer require grazulex/laravel-draftable

๐Ÿ’ก Auto-Discovery: The service provider will be automatically registered thanks to Laravel's package auto-discovery.

โšก Quick Start

use Grazulex\LaravelDraftable\Traits\HasDrafts;

// Add to your model
class Post extends Model
{
    use HasDrafts;
    
    protected $fillable = ['title', 'content', 'status'];
}

// Create and manage drafts
$post = Post::create(['title' => 'My First Post']);

// Make changes and save as draft
$post->title = 'Updated Title';
$post->content = 'Draft content here...';
$post->saveDraft();

// Publish when ready
$post->publishDraft();

// View version history
$versions = $post->drafts;

// Compare versions using the service
$draftDiff = app(\Grazulex\LaravelDraftable\Services\DraftDiff::class);
$diff = $draftDiff->compare($version1, $version2);

// Restore previous version
$post->restoreVersion(2);

๐Ÿ”ง Requirements

  • PHP 8.2+
  • Laravel 11.0+

๏ฟฝ Complete Documentation

For comprehensive documentation, examples, and advanced usage guides, visit our Wiki:

๐Ÿ“– ๐Ÿ‘‰ Laravel Draftable Wiki

The wiki includes:

๐ŸŽจ Artisan Commands

Laravel Draftable includes powerful CLI commands for draft management:

# List all drafts with filtering options
php artisan draftable:list --model=Post --unpublished --limit=20

# Compare two specific versions of a model
php artisan draftable:diff Post 1 1 2 --format=json

# Clean up old drafts with safety checks
php artisan draftable:clear-old --days=30 --dry-run

๐Ÿ” Advanced Features

Version Comparison

use Grazulex\LaravelDraftable\Services\DraftDiff;

$draftDiff = app(DraftDiff::class);
$differences = $draftDiff->compare($draft1, $draft2);

// Example output:
[
    'title' => [
        'type' => 'modified',
        'old' => 'Original Title',
        'new' => 'Updated Title'
    ],
    'content' => [
        'type' => 'added',
        'old' => null,
        'new' => 'New content here'
    ]
]

Events Integration

use Grazulex\LaravelDraftable\Events\{DraftCreated, DraftPublished, VersionRestored};

// Listen for draft events
Event::listen(DraftCreated::class, function ($event) {
    // Handle draft creation
});

Event::listen(DraftPublished::class, function ($event) {
    // Handle draft publication
});

Event::listen(VersionRestored::class, function ($event) {
    // Handle version restoration
});

Database Migration

The package includes an optimized migration:

Schema::create('drafts', function (Blueprint $table) {
    $table->id();
    $table->morphs('draftable');
    $table->json('payload');
    $table->unsignedBigInteger('version')->default(1);
    $table->foreignId('created_by')->nullable()->constrained('users');
    $table->timestamp('published_at')->nullable();
    $table->timestamps();

    // Performance indexes
    $table->index(['draftable_type', 'draftable_id']);
    $table->index('published_at');
    $table->index('version');
});

๐Ÿ“Š Quality Metrics

Laravel Draftable maintains exceptional quality standards:

  • โœ… 128/128 tests passing (100% success rate)
  • โœ… 93.6% code coverage (enterprise grade)
  • โœ… PHPStan level 5 (zero static analysis errors)
  • โœ… PSR-12 compliant (Laravel Pint)
  • โœ… SOLID principles (clean architecture)
  • โœ… Production ready (zero known issues)

๐ŸŽฏ Use Cases

Perfect for:

  • Content Management Systems - Blog posts, articles, pages
  • E-commerce Platforms - Product descriptions, specifications
  • Documentation Sites - Version-controlled documentation
  • Marketing Campaigns - Draft and schedule content releases
  • User-Generated Content - Moderation workflows with drafts
  • API Content - Versioned API documentation and responses

๐Ÿ”ฎ Roadmap

Future enhancements planned:

  • ๐Ÿ”— Webhook Integration - HTTP notifications on publish events
  • ๐ŸŽฏ Git-style Delta Storage - Space-efficient version storage
  • ๐Ÿ”„ Approval Workflows - Multi-step moderation processes
  • ๐Ÿ“ฑ API Endpoints - RESTful API for external integrations
  • ๐ŸŒ Multi-language Support - Internationalization features

๐Ÿค Contributing

Please see CONTRIBUTING.md for details.

๐Ÿ”’ Security

If you discover any security-related issues, please email jms@grazulex.be instead of using the issue tracker.

๐Ÿ“ Changelog

Please see RELEASES.md for more information on what has changed recently.

๐Ÿ“„ License

The MIT License (MIT). Please see License File for more information.

๐Ÿ‘ฅ Credits

๐Ÿ’ฌ Support

Laravel Draftable - Production-ready drafts and versioning
for any Eloquent model with enterprise-grade quality.

Built with โค๏ธ following SOLID principles and clean code practices.