Filament Enum Plural Label Laravel Package

Product Decisions This Supports

• Platform upgrade sequencing (primary): v2.0.0 is a hard compatibility cut — PHP 8.2+, Laravel 11.28+/12/13, Filament v5+ — with PHP 8.1 and Filament v3/v4 explicitly dropped. If Filament 5 is on the roadmap, this package is no longer the blocker; the decision becomes when to run the coupled upgrade of app + Filament + this package, not whether.
• Build vs buy for enum-backed form fields: the package's surface is small (string/int/pure enums → options/labels, Htmlable rendering, null handling, Filament resource wiring). An in-house implementation is plausibly 50–150 lines. Decision hinges on maintenance appetite vs. dependency/upgrade coordination cost, not on capability.
• Adoption risk scoring: the release adds 19 tests / 34 assertions on a PHP 8.2/8.3/8.4 CI matrix. That is a meaningful credibility step for a small utility, but treat it as a floor — it covers the contract surface (enum variants, Htmlable, null, resource integration), not depth or performance. No static analysis or coverage threshold is stated.
• Dependency-surface governance: declaring illuminate/contracts (^11.28|^12.0|^13.0) explicitly, and including Laravel 13 in the constraint, is a forward-compatibility signal. It reduces the odds of a future "works on Filament 5 but not Laravel 13" surprise, which matters if this ships in a long-lived product line.
• Support-window policy: v1.x is now the designated branch for PHP 8.1 / Filament 3–4 consumers. Decide explicitly how long v1.x is expected to receive fixes, and whether any team or client deployment must be pinned there.
• Forcing function for migration: because the break is simultaneous across PHP and Filament majors, adopting v2 doubles as a checkpoint that the platform upgrade actually completed end-to-end — useful as a canary in a broader Filament 5 rollout.

When to Consider This Package

Consider adopting when:

• The application is already on, or committed to, PHP 8.2+, Laravel 11.28+/12/13, and Filament v5.
• Enums are the source of truth for select/radio option sets, and you want labels — including rich HTML labels (icons, badges, formatting) via Htmlable — without custom glue code per resource.
• You need consistent handling of the awkward cases: string-backed, int-backed, and pure/unit enums, plus null returns.
• You want to avoid owning a small internal helper across multiple Filament major upgrades.
• You are comfortable with a small, single-surface dependency whose upgrade cadence tracks Filament majors.

Look elsewhere or hold when:

• Pinned to PHP 8.1 or Filament 3/4 — stay on v1.x and schedule migration; do not take v2 into an environment that cannot satisfy PHP 8.2.
• You have exactly one or two enums — an in-house helper is likely cheaper than a dependency plus coordinated major upgrades.
• Requirements exceed label/option rendering: cascading or dependent selects, remote/lazy-loaded option sets, large option collections (thousands of cases), or a translation/localization pipeline. Validate these against the package before committing; the test suite does not cover them.
• You need contractual support, SLAs, or a guaranteed deprecation policy — this is a small-footprint package; vendoring or forking remains a reasonable hedge given how little code is involved.
• You are mid-freeze on the application's platform versions and cannot absorb a breaking dependency bump this cycle.

How to Pitch It (Stakeholders)

For executives: This is a maintenance-grade release, not a new capability — it adds Filament 5 / PHP 8.2+ support, an automated test suite, and CI. Product impact is schedule, not features: it removes this package as an obstacle to the Filament 5 upgrade and gives us a concrete milestone to plan the platform migration around. Cost is contained — the package is small, its surface is narrow, and if it ever stalls we can replace it in-house. The one thing to note is that it is a breaking release: environments on PHP 8.1 or Filament 3/4 must stay on v1.x until their upgrade lands, so we should confirm the migration window rather than let the two drift.

For engineering: Breaking change — PHP 8.1 and Filament 3/4 are dropped; use v1.x if you need to defer. On upgrade: bump the constraint, verify illuminate/contracts resolves against your Laravel version (11.28+/12/13 are supported, including 13), and audit every enum-backed field — particularly the Htmlable label path and any null-returning label logic, since those are the areas the new contract and tests target. The added suite (19 tests / 34 assertions, PHP 8.2–8.4 matrix) is a good signal but a thin one; run it in our pipeline and treat any gap in our own enum usage as ours to cover. Pin v1.x on any branch that cannot move PHP or Filament this cycle, and track when that pin can be dropped.