Laravel Drafts Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Modular Design: The package leverages Laravel’s Eloquent traits (HasDrafts) and integrates seamlessly with existing Laravel models, requiring minimal architectural changes.
  • Decoupled Logic: Draft/revision handling is encapsulated within the trait, avoiding pollution of business logic in controllers or services.
  • Query Scoping: Built-in query scopes (withoutDrafts(), withDrafts(), onlyDrafts()) align with Laravel’s Eloquent conventions, reducing cognitive load for developers.
  • Preview Mode: Facilitates admin previews without exposing drafts to the public, addressing a common UX requirement.
  • Relation Support: Handles HasOne, HasMany, BelongsToMany, and MorphToMany relations, making it versatile for complex models.

• Weaknesses:

  • Database Schema Coupling: Requires additional columns (is_current, is_published, uuid, etc.) per model, which may not align with existing schemas or microservices architectures.
  • Revision Storage: Revisions are stored as separate rows in the same table, which could bloat the database for high-frequency updates (e.g., CMS content with many drafts).
  • No Soft-Deletes for Revisions: While revisions support soft deletes, there’s no built-in mechanism to archive old revisions (e.g., for compliance or storage optimization).
  • Limited Customization: The package assumes a linear revision history; branching/merging drafts (e.g., Git-like workflows) isn’t supported.

Integration Feasibility

• Laravel Ecosystem Fit:

  • High: Designed for Laravel 9–13, with explicit support for Eloquent, query builders, and middleware. Composer dependency management simplifies adoption.
  • Middleware Integration: WithDraftsMiddleware enables granular route-level access control for drafts, useful for admin panels.
  • Testing Support: Includes PHPUnit tests and a composer test command, easing CI/CD integration.

• Non-Laravel Systems:

  • Low: Not applicable outside Laravel due to Eloquent dependency. Would require significant refactoring for frameworks like Symfony or custom PHP.

• Database Compatibility:

  • MySQL/PostgreSQL/SQLite: Fully supported (uses Eloquent’s query builder).
  • NoSQL: Not supported; revisions rely on relational database features (e.g., UUIDs, foreign keys).

Technical Risk

Key Questions for Stakeholders

1. Database Strategy:

   • Are we willing to add 5+ columns to every draft-enabled model? If not, can we extend the package to support a separate revisions table?
   • How will we handle revision cleanup (e.g., purging old drafts for compliance)?

2. Workflow Requirements:

   • Do we need branching/merging of drafts (e.g., for collaborative editing)? If so, this package may not suffice.
   • Should drafts support versioning metadata (e.g., author_id, change_description)?

3. Performance:

   • What’s the expected update frequency for draft-enabled models? (High-frequency updates may bloat the DB.)
   • Are there read-heavy queries that could benefit from caching drafts?

4. Deployment:

   • How will we handle drafts during deployments? (e.g., avoiding lost drafts during zero-downtime updates.)
   • Should drafts be excluded from backups or require separate retention policies?

5. Alternatives:

   • Have we evaluated other packages (e.g., spatie/laravel-activitylog for revisions, or custom solutions)?
   • Is the MIT license acceptable for our use case?

Integration Approach

Stack Fit

• Primary Fit:

  • Laravel Applications: Ideal for content-heavy apps (CMS, blogs, marketing sites) where drafts/revisions are critical.
  • Eloquent-Based Models: Works best with models using Eloquent ORM (not Query Builder or raw SQL).
  • Admin Panels: Preview mode and middleware are tailored for admin interfaces (e.g., Nova, Filament, or custom backends).

• Partial Fit:

  • APIs: Can be used for draft endpoints, but requires careful scoping to avoid exposing drafts to clients.
  • Real-Time Systems: Not optimized for WebSocket-based collaboration (e.g., live editing).

• Non-Fit:

  • Non-Laravel PHP: Requires rewriting core logic.
  • Headless CMS: If drafts are managed externally (e.g., Strapi, Directus), this package adds unnecessary overhead.

Migration Path

1. Assessment Phase:

   • Audit existing models to identify draft requirements (e.g., Post, Page, Product).
   • Validate database schema compatibility (e.g., can we add uuid() columns without downtime?).

2. Pilot Implementation:

   • Start with a single model (e.g., Post) to test:
     • Trait integration (use HasDrafts).
     • Relation sync (e.g., tags for a blog post).
     • Preview mode in admin routes.
   • Use feature flags to toggle drafts on/off during testing.

3. Incremental Rollout:

   • Phase 1: Enable drafts for content models (low-risk, high-impact).
   • Phase 2: Extend to complex relations (e.g., polymorphic MorphToMany).
   • Phase 3: Optimize (e.g., add revision cleanup cron jobs).

4. Database Migration:

   • Use the drafts() schema helper to add columns in a single migration:

     Schema::table('posts', function (Blueprint $table) {
         $table->drafts();
     });
     

   • For zero-downtime deployments, consider a two-step migration:
     1. Add new columns.
     2. Backfill existing records (if needed).

Compatibility

• Laravel Versions:

  • Supported: 9.x (v1.x), 10.x (v1.x), 11.x (v2.x), 12.x (v3.x+).
  • Recommendation: Use the latest minor version (e.g., v3.x) for bug fixes and Laravel 13 support.

• PHP Versions:

  • Supported: 8.0–8.4 (check composer.json for exact ranges).
  • Recommendation: Align with Laravel’s PHP requirements (e.g., 8.2+ for LTS).

• Dependencies:

  • Conflicts: None major; uses Laravel’s core contracts (illuminate/contracts).
  • Extensions: Works with common packages (e.g., Spatie’s MediaLibrary, ActivityLog) if relations are marked as draftable.

Sequencing

1. Pre-requisites:

   • Laravel 9+ application with Eloquent ORM.
   • Composer and PHP 8.0+ environment.
   • Database with schema migration support.

2. Installation Order:

   composer require oddvalue/laravel-drafts
   php artisan vendor:publish --tag="drafts-config"
   

   • Configure config/drafts.php (e.g., adjust revisions.keep or column names).

3. Model Integration:

   • Add HasDrafts trait to target models.
   • Define $draftableRelations for models with relations.
   • Run migrations to add draft columns.

4. API/Route Integration:

   • Add WithDraftsMiddleware to admin routes.
   • Implement preview mode in admin controllers/views.

5. Testing:

   • Unit tests for model methods (createDraft, saveAsDraft, revisions).
   • E2E tests for draft workflows (e.g., create → preview → publish).

6. Monitoring:

   • Log revision creation/deletion to track usage.
   • Monitor database growth (e.g., SELECT COUNT(*) FROM posts WHERE is_published = 0).

Operational Impact

Maintenance

• Pros:
  • Low Overhead: Minimal maintenance after initial setup (no external services to manage).
  • Community Support: 436 stars and active development (last release: 2026-05-19).
  • Configurable: Centralized settings in config/drafts.php for easy adjustments (e.g