Filament Enum Plural Label Laravel Package

Technical Evaluation

What changed. v2.0.0 is a compatibility release, not a feature release. It targets Filament v5, raises the PHP floor to 8.2, declares illuminate/contracts (^11.28|^12.0|^13.0) explicitly for the Htmlable type, and — most importantly from a governance standpoint — adds the package's first automated test suite (19 tests / 34 assertions) and a GitHub Actions CI matrix across PHP 8.2/8.3/8.4.

Architecture fit. The package occupies a small, well-bounded slot: it converts enum-backed values (string-backed, int-backed, and unit enums) into display output that is string, int, Htmlable, or null, and integrates with Filament resources. That is a narrow surface with few architectural dependencies — it does not own persistence, routing, auth, or queue behaviour. The explicit illuminate/contracts declaration is a genuine improvement: previously the Htmlable type was implicitly satisfied by the framework, and an undeclared transitive dependency is exactly the kind of thing that breaks silently on a Laravel major. This is a maturity signal, not just a version bump.

Integration feasibility. High, with one caveat. The constraint set (PHP 8.2+, Laravel 11.28+/12/13, Filament 5+) mirrors Filament 5's own upstream requirements, so the package is tracking the framework rather than inventing its own envelope — low risk of divergence. The caveat is Laravel ^13.0: no Laravel 13 exists in the wild yet, so that constraint is aspirational. Accepting it in require is forward-friendly but means the CI matrix cannot actually validate it. We would be running on Laravel 11.28/12 only, and should treat 13 as untested until upstream ships.

Technical risk.

• Breaking change is real but contained. Dropping PHP 8.1 and Filament v3/v4 will hard-fail composer update on any lagging panel. The package correctly points users at v1.x, which converts a hard break into a branch-pinning exercise — acceptable, provided v1.x is actually maintained (see below).
• Test suite is new, not mature. "Extensive" overstates 19 tests / 34 assertions. The stated coverage — enum variants, Htmlable, null, and one Filament resource integration — is a reasonable smoke net, but the phrase "Filament resource integration" in the singular suggests the highest-risk area (real panel rendering, Livewire lifecycle, table/column rendering) is the thinnest. There is no evidence of static analysis (PHPStan/Psalm), a code-style gate, coverage reporting, or a security policy.
• Htmlable implies raw HTML. Any path that returns Htmlable bypasses Blade escaping. Whether the package sanitizes or delegates entirely to the caller is the single most important thing to verify before we rely on it for user-influenced data.
• null returns fail silently. A null display result is a blank cell in a Filament table — no exception, no log. Low blast radius but poor observability.
• Maintainer concentration. No signal here on bus factor, release cadence, or security disclosure process. Filament's v3→v4→v5 cadence has been fast; a single-maintainer package chasing three majors in quick succession is a sustainability question, not a technical one, and belongs in the review.

Key questions for the maintainer.

1. Is v1.x in maintenance — bug fixes only, or security fixes only — and for how long? What is the published EOL date?
2. Does the "Filament resource integration" test exercise an actual panel/table render, or a container-resolved mock?
3. Is Htmlable output sanitized by the package, or is escaping entirely the caller's responsibility? Please document whichever it is.
4. Is ^13.0 in illuminate/contracts declared pre-emptively, or has it been tested against a 13.x-dev branch?
5. Are PHPStan (level ≥ 6) and a code-style gate planned, or is PHPUnit the whole quality story?
6. What is the security disclosure channel, and what is the expected turnaround for a Filament 6 compatibility release?

Integration Approach

Stack fit. Clean, provided we are already on PHP 8.2+ and Laravel 11.28+. This is a presentation-layer dependency only — it has no migration, no config publish requirement mentioned, and no runtime service that needs supervising. It belongs in require (not require-dev) for any panel that uses it, and is safe to isolate to the panel-facing application layer rather than shared domain packages.

Compatibility matrix.

Migration path. The upgrade is monotonic and cannot be done in one step — the package bump is the last action, not the first:

1. Runtime first. Move the affected services to PHP 8.2+. This is usually the slowest step organisationally (base images, CI runners, local dev parity) and gates everything else.
2. Laravel second. Reach 11.28+ (or 12). Do this with the package still on v1.x; the package is not the constraint here.
3. Filament third. Upgrade panels v3/v4 → v5, still on v1.x, so any breakage is unambiguously Filament's and not the package's.
4. Package last. Bump to v2.0.0. At this point the diff should be near-zero and any failure is clearly attributable.

Sequencing and scope. Treat this as a ride-along on the Filament 5 upgrade, not a standalone project. If the Filament 5 migration is already funded, adding this is a few hours. If it is not, this package is not a reason to start one — pin v1.x, add a ticket to the Filament 5 epic, and move on.

Guardrails.

• Pin exactly ("vendor/package": "2.0.0") rather than floating ^2.0, at least for the first cycle; a 2.0.x patch on a package with 19 tests should be reviewed, not auto-adopted.
• Add a Composer conflict or documented constraint so a partial upgrade (Filament 5 with package v1.x, or vice versa) fails loudly at install time rather than at render time.
• If multiple panels exist, verify each one independently — a mixed estate (one panel on v4, one on v5) forces a split-package or a deferred upgrade, and that decision should be made deliberately.

Operational Impact

Maintenance. Low steady-state cost, but the dependency maintenance is the real load: this package's release cadence is dictated by Filament's major cadence, and Filament has shipped v3 → v4 → v5 in short order. Expect a v3.0.0 within roughly the same interval Filament takes to ship v6, and expect it to be another breaking drop of the previous Filament major. Budget for a recurring, small, forced-upgrade task, not a one-off.

Support. No vendor; support is the maintainer's issue tracker plus our own reading of a small codebase. Before adoption, ask for the maintenance/EOL statement for v1.x — if v1.x goes dark the moment v2 ships, any panel we cannot move to Filament 5 becomes a blocked upgrade with no upstream fix path. That is the single largest support risk and it is a policy question, not a code question.

Scaling. Effectively irrelevant at our scale. This is per-request formatting logic with no I/O, no caching layer, no state. The only scaling-adjacent concern is rendering large tables: if the package performs enum reflection per cell, it is worth a glance at a 500-row table, but the return types suggest simple resolution and the risk is negligible. No horizontal-scaling implications.

Failure modes.

• Install-time hard failure — Composer resolves against PHP 8.1 or Filament v4 and refuses. Loud, safe, and the desired behaviour.
• Silent blank cells — a null return renders nothing with no warning. Symptom is a UI gap reported by a user, not an alert. Mitigation: assert non-null on a sample of enum-backed columns during the upgrade, and check for empty columns in the smoke test.
• Escaping regression — if a Htmlable path is fed user-controlled content and is not sanitized, this becomes an XSS vector and a security incident rather than a bug. This is the failure mode that justifies the review question above; do not adopt for untrusted input until it is answered.
• Untested Laravel 13 — a future Laravel 13 install will satisfy constraints without CI ever having run against it. Symptom would be a subtle contract mismatch in Htmlable. Mitigation: only move to Laravel 13 after this package (or a successor release) has CI coverage for it.
• Maintainer abandonment — package stops tracking Filament. Symptom is a blocked Filament upgrade. Mitigation: the package is small; confirm we have the licence and appetite to fork or vendor it if needed.

Ramp-up. Minimal for engineers — the API is a handful of enum-to-display conversions over a standard Filament idiom, and anyone who has written a Filament column will be productive in well under an hour. The genuine ramp-up cost sits with platform work: getting the estate onto PHP 8.2+ and Filament 5. Assign the upgrade to whoever owns the Filament 5 migration, not to a feature team, and document the v1.x-vs-v2.0.0 pinning rule in the repo README so the next engineer does not discover the break via a failed composer update.