Filament Drafts Laravel Package

Technical Evaluation

Architecture fit. The package is a Filament v3 plugin built on a narrow, legible pattern: a shadow draft table mirrors each base Eloquent table, a trait is applied to a draft model, and a publish action promotes the draft row into the canonical table. That is a good architectural match when the product runs Laravel + Filament v3, the drafted entities are flat-schema Eloquent resources (pages, posts, announcements, policy documents), and the editorial workflow is the happy path of stage → preview → publish. It is a poor fit for relationship-heavy content models (BelongsToMany with pivots, media attachments, nested repeaters), for regulated audit requirements, and for any roadmap that includes a Filament v4 migration in the near term — plugins are effectively version-locked to the panel they were built against.

The abstraction is thin — plausibly 300–500 lines of trait plus shadow-table logic. That cuts both ways: it means low magic and easy debuggability, but also that the build-vs-buy delta is small. The honest framing for the roadmap is buy the convention, not the code: what we're acquiring is a validated shape for the problem, not a moat.

Integration feasibility. Feasible for a mid-level Laravel engineer in a short spike. The install is standard (composer require guava/filament-drafts:2.1.1, publish config, publish migrations, register the plugin on the panel), and the per-model work is a mechanical five-step routine: draft flag column, mirrored draft table, draft model with re-declared $fillable/$casts/validation, trait + resource rebinding, publish actions and policy ability, feature test. The second and third resources cost a fraction of the first, which is the key economic argument — but only if we enforce the convention.

Technical risk. Concentrated in five places, roughly by severity:

• Schema drift between base and draft tables is the number-one failure mode. Adding a column to pages and forgetting page_drafts silently drops editorial content on the next publish. This presents as a UI bug and costs a day to diagnose. It is a process risk disguised as a code risk, and it recurs on every future migration.
• Maintenance concentration. Zero dependents and a single maintainer means no production evidence anywhere. The 2.x line is quiet — fine for churn, bad for undiscovered bugs. The latest release is a translation fix that also touched tab translations, a concrete signal that form/tab lifecycle interception is an active surface where other Filament plugins can collide.
• Undocumented publish semantics. The docs do not state whether publish is an overwrite, a merge, or transactional. This matters the moment publish fires model events we hook for slug generation, cache invalidation, sitemap pings, or notifications — an observer firing on a half-promoted record is how a broken link reaches production.
• Global scope leakage. "Automatically hide drafts from public queries" is both the feature and the trap. Every consumer must be audited: public controllers, sitemaps, search indexes, RSS, API resources, queued jobs. The admin panel must equally bypass the scope, or editors open to an empty list.
• Constraint and relationship collisions. Unique slugs shared between draft and live rows, and relationship graphs that draft tables do not carry, are both unresolved until spiked.

Key questions to resolve before committing:

1. Does the package create draft tables, or ship a stub we copy per model? This single fact sets the size of the integration.
2. What exactly does the trait inject — which scopes, global or opt-in? That determines the audit surface across the whole app.
3. Is publish atomic? What happens to model events and side effects on partial failure?
4. How are relationships, media, and repeaters resolved at publish time — from the draft or the base model? Are pivot rows duplicated or shared?
5. Is revision pruning configurable, and what is the growth curve of the revision table?
6. What Laravel/PHP/Filament version bounds are actually declared, and is there any maintainer signal on v4?
7. What is our fallback if a v4 upgrade lands in the roadmap — fork, or replace with an is_published column plus audit log?

Integration Approach

Stack fit. Clean, but conditional. Laravel + Filament v3 admin panel, ordinary Eloquent resources, editors who are non-technical and need edit/publish separation with preview. If the drafted surface is customer-facing legal copy or anything with approval stages, we get governance value nearly free by defining a distinct publish policy ability rather than reusing update — junior editor stages, senior editor flips live. That is a product capability worth calling out explicitly in the plan, not an implementation detail.

Migration path. Two distinct migrations, and they should not be conflated:

• Schema: mirrored draft tables per model, created via a shared column builder so base and draft stay in lockstep by construction.
• Data: a one-off backfill marking every existing row as published. Without it, editors open the admin and see the entire historical content set presented as unpublished drafts — confusing at best, an accidental mass publish at worst. This must land before anyone sees the UI, and it should be the same release.

Compatibility. Three verified risks and one unknown. Verified: Filament v3 lock-in; save-pipeline collisions with other lifecycle-hooking plugins (translatable, media library, other revision packages) — spike the pair together before rollout if translatable is in play; and thin localization (FR ships, other locales need a lang-file PR or vendor override). Unknown: declared Laravel/PHP bounds — confirm against our runtime rather than assuming.

Sequencing. Ship one low-risk, flat-schema, non-customer-facing model end-to-end — Page, Post, or Announcement — through all six validation steps (draft model, trait, resource renders unchanged, publish action on both row and header, public query excludes unpublished, publish/edit/publish cycle leaves the canonical row untouched). If the resource render or the public query misbehaves, stop: price the in-house replacement there rather than after three models are wired. Then run it for a release cycle with real editors before the second resource. Layer preview as a signed, short-lived draft-bound URL — never as publish-to-secret-slug, which pollutes the canonical table and defeats the point. Schedule revision pruning from day one if the package does not offer it. Record the v3 lock-in and the fork contingency in the ADR.

Operational Impact

Maintenance. The install is cheap; the ownership is not. Budget a named owner at a few hours per quarter plus a hard rule in the PR template: every migration on a drafted model is a two-table change. Back it with a CI test that diffs information_schema column sets for each base/draft pair and fails on divergence — this check is the single highest-ROI artifact in the whole adoption. Pin 2.1.1, commit composer.lock, and keep a one-page runbook: where the trait lives, how to fork, what the publish path does.

Support. Effectively internal. Single maintainer, zero dependents, low cadence. Upstream responsiveness is unproven — treat bug discovery as our job, not theirs. Translation gaps and any v4 gap should be planned as forks or vendor overrides, not as upstream requests with a delivery date attached.

Scaling. The pattern doubles write surface per drafted model and adds a promote step on publish. The real scaling cost is the revision table: assume unbounded growth until proven otherwise, and check configurability early — if it grows unchecked it will become the largest table in the database. Read-path overhead from the draft-exclusion scope is negligible relative to the correctness burden of applying it everywhere. There is no production-scale evidence to lean on, so load behavior on large tables is an open question, not an assumption.

Failure modes to plan for, with detection:

Ramp-up. Low for engineers already fluent in Filament — the first resource is a day, subsequent ones are hours. Editor training is the real onboarding cost: the mental model of "your edits are not live until you publish" needs to be taught, not assumed, and the publish action belongs in both row actions and the page header because editors will look in both places. Validate behavior with database-level feature tests on the four semantics that matter (publish creates/updates canonical, unpublish removes from public query, draft edits do not mutate canonical, failed publish leaves no half-promoted record) rather than against Livewire responses — that keeps the test suite honest as the UI evolves.