Product Decisions This Supports
- Major-version migration as a roadmap gate. Filament v4 → v5 is a forced decision point: deprecations, namespace/API shifts, and Tailwind 3+ assumptions mean every v4 admin panel eventually hits an "upgrade or freeze" fork. This package turns that fork into a scheduled, estimate-able work item rather than an open-ended refactor, which is what a roadmap needs.
- Build vs. buy on migration tooling. The alternative is (a) manual refactor, (b) an internal codemod, or (c) staying on v4 past end-of-support. An official, MIT-licensed, CLI-driven upgrade path is the cheapest defensible option — but budget it as assistive, not turnkey: the deliverable is "automated mechanical changes + a scoped manual backlog," not "zero-touch upgrade."
- Sequencing and scope decisions. Because the tool is run per-branch and supports dry-run analysis, it makes phased rollout a real choice: which panels go first, whether v5 lands behind feature flags, whether the team upgrades low-traffic admin surfaces before core CRUD workflows. That's a PM decision the tooling now enables rather than blocks.
- Feature adoption timing. v5's gains (performance, updated UI components, Tailwind 3 alignment) are only realizable once migration cost is bounded. This package is the unlock condition for roadmap items that assume v5 — new dashboard layouts, refreshed component library, plugin compatibility.
- Team-capacity planning. It lowers the Filament-expertise bar for the upgrade, which matters if the team is small, has one Filament specialist, or is onboarding. It converts a specialist task into a reviewable diff.
- Use cases worth naming: modernizing a legacy internal admin panel without touching core business logic; unblocking dependency updates that require v5; standardizing multiple Filament panels across products; de-risking acquisition/audit scenarios where you inherit an aging v4 codebase.
A candid caveat for the decision log: this is early-stage tooling — near-zero dependent adoption, a single-purpose scope, and no built-in rollback. Treat it as a dev dependency with an exit plan, not infrastructure. Verify command names, flags, and coverage against the actual release before committing dates; several details circulating in early assessments (e.g., percentage time savings, specific artisan command signatures) are estimates, not vendor guarantees.
When to Consider This Package
Adopt when:
- You run Filament v4 in production and have a dated intent to reach v5 — driven by support windows, plugin compatibility, or a roadmap feature that requires v5.
- The codebase is non-trivial (roughly 10+ resources/pages, custom widgets, policies), where hand-editing namespaces, method signatures, and config keys is where errors hide.
- You can isolate the upgrade: a branch, a staging environment, CLI access, and a rollback path (tag, backup, or feature flags). No rollback story, no upgrade.
- You have — or will build — test coverage over Filament behavior (CRUD, auth, policies, widgets). The tool changes code, not confidence; QA is the real gate.
- You want a fast inventory even before committing: a dry-run/analysis pass is a cheap way to size the work for planning.
Look elsewhere or defer when:
- You are not on Filament v4 — not applicable to v2/v3, and irrelevant to non-Filament admin panels.
- The app is small or Filament is peripheral — a handful of resources is faster to migrate by hand than to validate generated diffs.
- You have heavy custom plugins or bespoke abstractions — expect manual work regardless; the tool's leverage drops sharply.
- You need guaranteed, supported migration outcomes — with effectively no dependent base, you are an early adopter absorbing first-mover risk. Pair it with a fallback: pin v4, freeze feature work on the admin panel, or budget a manual contingency.
- Your org can't accept a no-rollback tool in the release path, or lacks CI/composer discipline to pin constraints cleanly.
Before committing, answer: What fraction of the panel is stock Filament vs. custom? Which third-party packages are v4-locked? Do we have automated tests over admin flows? Who owns post-upgrade triage for the first 30 days? What is the abort criterion and at which phase?
How to Pitch It (Stakeholders)
To executives: We're approaching a forced upgrade from Filament v4 to v5 — staying put means falling off support and losing access to security fixes, plugin updates, and the performance work our roadmap assumes. This package automates the mechanical portion of that migration: renamespacing, deprecated API replacements, config and template updates. It doesn't eliminate the work, but it shrinks the tedious, error-prone half and gives us a reviewable diff instead of a hand-refactor. Cost is small and one-time (a dev dependency, MIT-licensed, no vendor lock-in); the return is a shorter, more predictable migration window and less risk of stalled admin-panel feature work. The ask: approve a timeboxed spike — dry-run analysis plus a scoped estimate — before we commit to dates.
To engineering: This is the official v4→v5 upgrade CLI: it analyzes the codebase, reports deprecated/incompatible usage, and applies automated fixes you can preview before writing. Run it on a branch off a tagged v4 baseline; analyze first, review the report, then fix with dry-run, commit in small batches, test in staging, and only then flip composer.json to v5 and drop the tool. Expect it to handle namespaces, method signatures, config keys, and Blade directive paths — and expect to hand-fix custom widgets, plugin glue, and anything non-standard. Non-negotiables: a clean rollback point, tests (or explicit manual QA) across CRUD/auth/policies/widgets, and a named owner for post-upgrade triage. This is early-stage software with almost no adoption footprint — we validate its output, we don't trust it blindly.