Filament Enum Plural Label Laravel Package

Getting Started

This release is a compatibility release (Filament v5 / PHP 8.2+), so treat v2.0.0 as the baseline for any new work and as a coordinated upgrade if you are already on v1.x.

• Confirm your stack first. v2.0.0 requires PHP 8.2+, Laravel 11.28+ / 12 / 13, and Filament v5+. If you are still on Filament v3/v4 or PHP 8.1, stay on v1.x and pin it explicitly ("vendor/package": "^1.0") so a composer update doesn't drag you across the break.
• Install and verify the constraint resolution. composer require vendor/package:^2.0 — if Composer refuses, it is almost always the new explicit illuminate/contracts constraint (^11.28|^12.0|^13.0) rejecting an older Laravel 11 patch release. Bump laravel/framework to at least 11.28 rather than trying to fight the constraint.
• Look at the tests before the README. This release ships 19 tests / 34 assertions covering string, int and unit enums, Htmlable and null returns, and Filament resource integration. That suite is the most reliable specification of the contract's accepted return types — read it first, then skim the README for the interface name you need to implement.
• First use case: take an existing status/type enum on a model, implement the package's contract on it, and wire it into a Select in a form and a badge-style TextColumn in the table. One enum then feeds filter options, form choices and table rendering from a single source of truth — which is the whole reason to reach for this package over an inline options() array.

Implementation Patterns

Contract-on-the-enum. The idiomatic pattern is to implement the interface directly on a backed enum and let the enum own its own presentation: label, and (depending on which methods the contract exposes in your version) colour/icon. This keeps Status::Active->label() available everywhere — Filament resources, notifications, Blade, API serialisation — instead of duplicating a match expression in three places.

Backed enums for persisted state, unit enums for fixed sets. The test suite explicitly covers string, int and unit enums, so both are supported. Use backed enums where the value hits the database; use unit enums for things like a fixed set of display filters where there is no column value.

null means "fall back", not "empty". Returning null from the contract hands control back to Filament's default behaviour (e.g. humanising the case name). Use it deliberately on enum cases where the default is already correct, and return an explicit '' only when you genuinely want a blank label — the two are not interchangeable.

Htmlable for rich output. Returning an Htmlable (the reason illuminate/contracts is now a hard dependency) lets a label carry markup — a coloured dot, an icon span. Wrap this in a small dedicated value object or a HtmlString factory rather than building strings inline, so escaping decisions live in one auditable place.

Reuse one enum across the whole resource. A single enum typically drives the form Select (options(Status::class) or a mapped array), the table column badge, the table filter, and any infolist entry. When you add a case, all four update together — that consistency is the payoff and worth designing around from the start.

Mirror the package's test style. If you wrap or extend this package, copy its approach: one test per return-type variant (string / int / unit / Htmlable / null) plus a Livewire-level Filament resource test that actually renders the component. The Htmlable and null paths are the ones that regress silently.

Gotchas and Tips

• This is a breaking release. PHP 8.1 and Filament v3/v4 support are both dropped. Upgrade PHP and Filament before bumping this package, otherwise you get a confusing dependency-resolution failure that looks like the package's fault.
• The illuminate/contracts constraint is the sharp edge. ^11.28 is a floor on the whole Laravel 11 line. Projects pinned to 11.0–11.27 will fail to install with no obvious error message; run composer update laravel/framework first.
• Htmlable output is not automatically safe. If a label interpolates user-controlled data (a name, a note), sanitise before wrapping — Filament will render the markup as-is.
• Case order is option order. Filament derives select/filter ordering from enum declaration order. If product wants alphabetical or workflow order, reorder the cases or supply an explicit sorted array; don't assume the DB or cases() will do it for you.
• CI matrix is PHP 8.2–8.4. Match your local and CI PHP version to that range. A local 8.1 binary will produce failures that look like package bugs.
• Debugging a wrong label: check the case actually implements the contract — a partially-implemented enum falls back to Filament's default silently rather than erroring. A quick dd(MyEnum::Case->label()) in tinker isolates package vs. Filament-configuration issues in seconds.
• Extension points: before subclassing or writing a decorator, check whether the contract already exposes the method you need — the addition of an explicit Htmlable dependency suggests the contract's surface is stable and intended to be implemented, not wrapped. Where a config file or publishable stub exists, publish it and keep overrides in config/ rather than editing vendor code, so the next major bump stays a composer update.