Laravel Revisor Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package excels for applications requiring draft/publish/revision workflows (e.g., CMS, editorial systems, or multi-stage approval processes). It aligns well with Laravel’s Eloquent ORM and integrates seamlessly with FilamentPHP for admin UIs.
• Core Features:
  • Drafting: Temporarily save unpublished records.
  • Versioning: Track revisions with timestamps, authors, and diff capabilities.
  • Publishing: Transition drafts to live state with atomic updates.
  • Soft Deletes: Optional integration with Laravel’s soft deletes.
• Limitation: Primarily model-agnostic; requires explicit setup per Eloquent model. Not suitable for non-Eloquent data (e.g., raw database queries or non-ORM layers).

Integration Feasibility

• Laravel Compatibility: Works with Laravel 9+ (tested up to v10). Assumes standard Eloquent setup (no major framework modifications needed).
• Database Requirements:
  • Adds revisor table for metadata (revisions, drafts).
  • Supports PostgreSQL, MySQL, SQLite (via Eloquent).
  • No schema migrations: Package auto-generates tables on first install (risk: potential conflicts if manual migrations exist).
• API Surface:
  • Eloquent Traits: HasRevisions, HasDrafts for model-level integration.
  • Service Providers: Minimal configuration (publishes config for draft/publish policies).
  • Events: Revising, Revised, Drafting, Drafted for extensibility.

Technical Risk

• Migration Complexity:
  • Existing Data: No built-in tool to backfill revisions for pre-existing records (manual seeding required).
  • Schema Conflicts: Risk of table name collisions if custom revisor table names are used elsewhere.
• Performance:
  • Revision Storage: Stores full model snapshots (could bloat database for high-frequency revisions).
  • Query Overhead: Draft/publish operations add joins to revisor table (test under load).
• Dependency Risks:
  • Relies on Laravel’s Eloquent (no active queries or raw SQL support).
  • FilamentPHP add-on is optional but tightly coupled (may require Filament for full UX).

Key Questions

1. Data Volume: How many revisions are expected per model? Will snapshot storage impact DB size?
2. Workflow Complexity: Are there custom approval chains or multi-user collaboration needs beyond basic draft/publish?
3. UI Requirements: Is FilamentPHP already in use, or will a custom UI be built (e.g., Livewire/Inertia)?
4. Audit Needs: Does the team require additional metadata (e.g., IP addresses, user agents) beyond timestamps/authors?
5. Testing: Are there existing tests for draft/publish logic that could conflict with Revisor’s events?

Integration Approach

Stack Fit

• Primary Stack: Laravel 9+/10 with Eloquent ORM.
• Secondary Stack:
  • FilamentPHP: Recommended for admin UIs (package includes laravel-revisor-filament).
  • Alternatives: Custom Livewire/Inertia components or API endpoints for draft/publish actions.
• Database: Compatible with Laravel’s supported databases (no NoSQL support).

Migration Path

1. Pre-Integration:
   • Audit existing models for draft/publish logic (identify conflicts or redundant features).
   • Backup database before installation (critical for production).
2. Installation:
   • Composer install: composer require indracollective/laravel-revisor.
   • Publish config: php artisan vendor:publish --tag="revisor-config".
   • Run migrations: php artisan migrate (auto-creates revisor table).
3. Model Integration:
   • Use traits in Eloquent models:

     use IndraCollective\Revisor\Traits\HasRevisions;
     use IndraCollective\Revisor\Traits\HasDrafts;
     
     class Post extends Model {
         use HasRevisions, HasDrafts;
     }
     

   • Configure policies in config/revisor.php (e.g., who can publish).
4. UI Layer:
   • For Filament: Install laravel-revisor-filament and configure resources.
   • For custom UIs: Build endpoints for draft(), publish(), and revisions() methods.

Compatibility

• Laravel Ecosystem:
  • Works with Laravel Scout, Nova, or Forge (no conflicts).
  • Caching: Revisions are DB-backed (no cache layer by default).
• Third-Party Packages:
  • Conflict Risk: Packages using revisor table names (unlikely, but check).
  • Event Listeners: Ensure no duplicate Revising/Revised listeners exist.
• Testing:
  • Package includes PHPUnit tests (verify against Laravel version).
  • Test draft/publish flows with Pest or Laravel Dusk.

Sequencing

1. Phase 1: Pilot with a non-critical model (e.g., BlogPost).
2. Phase 2: Integrate Filament UI or custom endpoints.
3. Phase 3: Roll out to high-traffic models (monitor DB growth).
4. Phase 4: Extend with custom events or middleware (e.g., auto-publish on schedule).

Operational Impact

Maintenance

• Package Updates:
  • Monitor GitHub Releases for breaking changes.
  • Dependency Risk: MIT license (low risk), but no active maintainer beyond IndraCollective.
• Customizations:
  • Override default behaviors via events (e.g., Revising to add custom metadata).
  • Extend RevisorServiceProvider for global policies.
• Documentation:
  • Official docs are readme/docs mature but lack advanced use cases (e.g., bulk revisions).

Support

• Troubleshooting:
  • Common issues: Missing migrations, trait conflicts, or Filament resource misconfigurations.
  • Debug with php artisan revisor:list-revisions (built-in CLI).
• Community:
  • Low Activity: 19 stars, 0 dependents (limited community support).
  • Alternatives: Consider spatie/laravel-activitylog for broader audit needs.
• Vendor Lock-in:
  • Minimal (uses standard Laravel patterns). Migration to another solution is feasible via custom traits.

Scaling

• Database Scaling:
  • Revisions Table: Partition by revisable_type if storing millions of revisions.
  • Indexing: Ensure revisable_type, revisable_id, and created_at are indexed.
• Performance:
  • Drafts: Lightweight (only metadata stored).
  • Revisions: Full snapshots (consider archiving old revisions to a separate DB).
• Concurrency:
  • Race Conditions: Draft/publish operations are atomic (Laravel DB transactions).
  • Locking: No built-in optimistic/pessimistic locking (add custom logic if needed).

Failure Modes

• Data Corruption:
  • Risk: Manual DB edits to revisor table could break revisions.
  • Mitigation: Use transactions for all draft/publish operations.
• UI Freezes:
  • Risk: Filament resource loading all revisions for a model (slow for large datasets).
  • Mitigation: Paginate revisions or lazy-load.
• Incomplete Migrations:
  • Risk: Forgetting to run php artisan migrate after install.
  • Mitigation: Add migration check to AppServiceProvider.

Ramp-Up

• Developer Onboarding:
  • Time Estimate: 2–4 hours to integrate a single model (longer for Filament UI).
  • Key Concepts:
    • draft() vs. publish() methods.
    • revisions() relationship.
    • Event system for extensions.
• Testing Strategy:
  • Unit Tests: Mock Eloquent models to test traits.
  • Integration Tests: Verify draft/publish flows end-to-end.
  • Load Tests: Simulate high revision volumes (e.g., 10k revisions).
• Training:
  • Docs: Official docs cover basics; supplement with internal runbooks for custom workflows.
  • Examples: Share pilot model integration as a template.