Filament Docs Laravel Package

Technical Evaluation

Architecture fit

• Filament-native, not a parallel stack. The package extends Filament's resource, relation-manager, and action primitives rather than introducing a second admin paradigm. On a team already standardized on Filament, the architectural delta is small: two models (Document, DocumentTemplate), a plugin registration, a facade-backed variable registry, and a print/PDF render path.
• Editor consolidation is the headline win in v5. Tiptap is removed in favor of Filament's built-in RichEditor for both template and document bodies. One editor stack, one asset pipeline, one upgrade surface — a material reduction in frontend coupling versus earlier releases.
• Clean extension seams. DocumentAction::make()->vars(...) for per-record values, FilamentDocs::register([...]) for global vars, and FilamentDocs::header/footer/css for branding. Branding and variable injection can be handled without forking, which matters for a package we may not want to own long-term.
• Scope boundary is honest but narrow. This is document authoring and rendering, not document governance. No e-signature, no approval workflow, no immutable versioning or audit trail, no retention policy, no document classification. Anything contract-critical beyond "generate, print, export PDF" is ours to build.

Integration feasibility

• Hard version gate. v5.0.0 targets Filament v5 with Laravel 12/13; Filament v3 is maintained on a separate v3 branch. Filament v4 appears to have no supported line. If we are on v4, the choice is upgrade to v5 or accept an unsupported island. This single question gates all estimation.
• Low-ceremony install: composer require, filament-docs:install, optional plugin registration, publishable config/views/lang/migrations. Realistic spike: 1–2 days in a branch to confirm migrations run clean, the panel renders, the variable registry resolves, and PDF output is acceptable.
• The PDF layer is the real external dependency and the docs are thin on it. Driver choice (DomPDF/Snappy-class) determines font support, page-break fidelity, repeated header/footer, image handling, and per-render cost. Validate against an actual contract-shaped template — multi-page, signature block, tables, logo — not a hello-world.
• Tenancy is manual work we own. ->isScopedToTenant() plus hand-written migrations adding team_id to documents and document_templates. Tenant isolation becomes our correctness problem, not the package's, including cross-tenant leakage through filters and relation managers.

Technical risk

• Adoption signal is weak. 45 stars, 0 dependents, single-maintainer ecosystem. There is no production peer group to lean on for edge cases. Mitigation is genuinely cheap, though: MIT license, small surface area, publishable Blade views — vendoring or forking is a credible fallback.
• Major-version churn. v1 → v2 → v5 in a short window with breaking changes across storage format, editor integration, and config keys. Any template HTML authored under Tiptap is not guaranteed to survive the RichEditor move; assume re-authoring rather than conversion.
• Sanitization is a behavior change, not just a fix. HTML is sanitized on save and on render. Templates relying on inline styles, custom classes, embedded fonts, iframes, or data attributes will silently degrade. For branded contract output this needs an explicit allowlist audit before sign-off.
• Print correctness. The bundled print stylesheet replacing the Tailwind CDN removes a network call at print time (good for regulated or restricted-network environments) but also means we inherit the package's print CSS baseline. Header/footer/page-break/branding overrides must be structured to survive upgrades.
• Security posture improved but not complete. Title/URL escaping in print-action JavaScript and HTML sanitization are addressed. Not addressed: authorization granularity on documents, tenant isolation guarantees, and the immutable audit expectations of a contracts system.
• Risk reducers: a new test suite spanning resources, print page, actions, relation manager, and the install command, plus shipped model factories for Document and DocumentTemplate. That meaningfully lowers our own test-authoring cost.

Key questions

1. Filament version: Are we on v5? If v4 — do we upgrade, or is v4 support on the maintainer's roadmap?
2. Migration scope: Do we have Tiptap-era templates anywhere in use? What is the re-authoring effort under RichEditor, and is there any conversion path?
3. Sanitizer policy: Is the sanitizer's allowlist configurable, or do we need a fork/patch to preserve required branding markup?
4. PDF driver: Which driver does the package assume, what is our fallback, and does output survive a legal review of layout fidelity?
5. Ownership: Are we comfortable with an effectively single-maintainer dependency for a revenue-adjacent artifact (contracts), or do we plan to vendor from day one?

Integration Approach

Stack fit

• Natural fit for an existing Filament panel on Laravel 12/13 with Filament v5. The package slots in as a panel plugin, inherits panel auth and (optionally) tenancy, and adds two resources plus an action and relation manager.
• If we are not already on Filament, this package is not a reason to adopt it — evaluate at the panel level, not the package level.
• Variable injection is declarative and maps well onto existing Eloquent records, so integration with our domain models is configuration rather than code.

Migration path

• Greenfield (recommended): install on a branch, publish config/migrations, author one real contract template end-to-end, run print and PDF, then decide. Nothing to migrate.
• From Tiptap-era templates: treat existing template HTML as incompatible-by-default. Plan a manual re-authoring pass per template and budget for it explicitly; do not assume markup survives the RichEditor and sanitizer changes.
• From a homegrown document feature: run the package in parallel behind a feature flag for one release cycle, port the template library, then cut over. Documents created in the old system need a one-way import script into the documents table — cheap, but must be scheduled.
• Tenancy enablement is a distinct migration step, not a config toggle: additive team_id columns, backfill of existing rows to the correct team, then enforcement. Backfill is where data-leak bugs are born; write it as a reviewed, reversible migration with an explicit orphan report.

Compatibility

• Pin to v5.x and pin the Filament major in the same constraint. Never allow a Filament minor upgrade to float the plugin version implicitly.
• Branch strategy must mirror the package's: if any part of our estate stays on Filament v3, that environment goes on the v3 branch and is treated as a separate, frozen dependency — with a stated end date.
• Verify the print/PDF driver against our server image (fonts, wkhtmltopdf/system libs) before committing; container parity failures here are common and late-surfacing.
• Confirm the bundled print stylesheet behaves under our CSP. If we run strict CSP, validate that the print page requires no inline script or CDN reference.

Sequencing

1. Week 1 — Feasibility spike (1–2 days engineering). Branch install, migrations, plugin registration, one real template, print + PDF fidelity check, sanitizer behavior on branded markup. Go/no-go with an evidence artifact, not an opinion.
2. Week 1 — Decision gate. Outputs: Filament version confirmed, PDF driver selected, vendoring decision made, sanitizer allowlist verdict.
3. Week 2 — Security and tenancy hardening. Tenant migrations and backfill, authorization policy review on document resources, cross-tenant filter testing.
4. Week 2–3 — Integration work. Register global vars against real models, wire DocumentAction into the resources that need it, implement header/footer/CSS branding via the facade (not by editing published views, so upgrades stay clean).
5. Week 3 — Operational readiness. Runbook for print/PDF failures, monitoring on render errors and queue depth, backup coverage for the new tables, admin training.
6. Week 4 — Controlled rollout. Feature flag to one team, one document type, then widen.

Operational Impact

Maintenance

• Small surface area, but real maintenance load: two models, migrations, published views, print CSS, and a PDF driver we own. Assign a named owner.
• Upgrade cadence is the primary cost. Major versions have arrived quickly with breaking changes. Budget a recurring slice of each quarter for plugin upgrades and a re-validation of template rendering after each Filament or plugin bump — not an ad-hoc scramble when a minor breaks print output.
• Custom branding must go through the facade hooks. Any direct edits to published views or the bundled print stylesheet become permanent upgrade friction; codify that as a review rule.
• Keep published views, CSS, and migrations in version control with a documented diff-from-upstream so we can see what we have customized.

Support

• There is no vendor support tier and effectively no community. 0 dependents and 45 stars means issues we file may not be answered. Assume self-support: we read the source, we patch, we carry the patch.
• Given MIT and a small codebase, establish a fork-or-vendor option before we need it — a private fork we can patch is a cheaper insurance policy than an emergency migration.
• Support burden concentrates in two places: template authors asking why markup degraded (sanitizer), and users reporting PDF layout differences (driver/fonts). Pre-empt both with a short internal guide and a template-authoring checklist.
• Track the maintainer's activity as a leading indicator. If releases stall for two consecutive Filament majors, trigger the fork decision rather than waiting.

Scaling

• Render cost is the scaling axis, not request volume. PDF generation is CPU- and memory-heavy and will dominate; a contract with images and many pages can take seconds per render.
• Offload PDF generation to a queue from day one, even at low volume. Synchronous rendering inside a Filament action will produce request timeouts under any burst, and it is far easier to build in now.
• Storage grows with document volume and PDF artifacts. Define retention for generated PDFs versus the source record, and decide whether regenerated PDFs are stored or produced on demand.
• Multi-tenant scale adds an isolation dimension: every resource query, filter, and relation manager must be verified tenant-scoped. Scale testing should include a cross-tenant access matrix, not just load.
• Concurrency: multiple users editing the same template is a lost-update scenario the package does not solve. Add optimistic locking or a governance convention if templates are shared.

Failure modes

• Silent markup degradation — sanitizer strips styling on save; output looks wrong but nothing errors. Detect with a golden-template render test in CI comparing against a known-good PDF/HTML snapshot.
• PDF render failure — driver-level errors (fonts, memory, malformed HTML) surface as opaque exceptions. Needs explicit error capture, user-facing messaging, and a documented retry path.
• Tenant leakage — the highest-severity mode, arising from manual team_id work and unscoped filters. Mitigate with automated tests asserting cross-tenant denial, plus a periodic audit query for orphaned or unassigned rows.
• Version drift — a Filament upgrade lands and print CSS or the plugin breaks. Mitigate by pinning, staging-first upgrades, and the golden-template test gate.
• Maintainer abandonment — no new releases for a Filament major. Detect via a scheduled dependency-review check; respond by activating the fork.
• Print-time asset dependency — largely resolved in v5 (bundled stylesheet, no CDN), but confirm our CSP and any custom header/footer partials introduce no external calls, particularly for restricted-network or regulated users.

Ramp-up

• Engineers: low. A Laravel/Filament developer is productive in under a day on the install, plugin registration, and DocumentAction wiring; half a day more for facade-based global vars.
• Template authors (non-engineering): moderate. RichEditor is familiar, but the variable syntax ($ACCOUNT_NAME), the sanitizer's limits, and print layout behavior all need hands-on training. Expect a short guide plus one supervised template build per author.
• Support/ops: low but non-zero — they need a triage path for "PDF is wrong" versus "template is wrong" versus "render failed," since those route to different owners.
• Overall: the package is easy to adopt and easy to run at small scale. The non-trivial costs are PDF fidelity validation, tenant isolation, sanitizer policy, and the standing commitment to track a fast-moving single-maintainer dependency. Those four items, not the install, should drive the go/no-go.