Filament Icons Laravel Package

Product Decisions This Supports

• Whether icons become a governed design-system surface or stay an informal convention. Icons are microcopy — they signal action, state, and hierarchy on every admin screen. This package converts whatever Blade icon sets are already installed into typed PHP enums (Heroicon::UserCircle instead of 'heroicon-o-user-circle'), turning the icon catalog into a named, reviewable, diffable artifact. That is a design-system governance call with an enforcement mechanism attached, not a developer convenience — and it is dramatically cheaper to answer this way than by commissioning a bespoke design-system package.
• Enforcement over guidance. If brand or UX rules say "these twelve icons are approved for navigation," an enum makes the approved set the only ergonomic option in the codebase. Off-catalog icons surface in code review rather than in QA or in front of a customer. The decision is whether to invest in design-system tooling at all; the cost of "yes" here is roughly one sprint-day plus a small CI gate.
• Build vs. buy for internal tooling. The alternatives are stringly-typed icon names (cheap today, expensive in defects) or an in-house enum generator (a few days plus permanent maintenance ownership). This sits in the narrow band where "buy" is defensible even from a single-maintainer package: integration cost is near zero, the output is plain PHP enums you own and commit, and the fallback is roughly a hundred lines of Artisan command. The exit cost is the whole argument.
• Refactor safety as product risk control. Dropping or renaming an icon becomes a static-analysis error at the reference site instead of a blank square in production. Removed cases are loud; renamed ones are silent — so the package needs a CI drift check to be genuinely safe, which is a process decision you are making alongside the dependency decision. Get that right and you widen how much UI iteration a small team can ship per sprint without added review burden.
• Multi-brand and white-label roadmap input. When icon sets differ per deployment or tenant theme, feature code references a stable symbolic name while the concrete set swaps underneath — provided you route call sites through a curated wrapper enum you own. This informs whether theming belongs in config or in code: cheap to decide now, painful to retrofit once a hundred call sites reference the raw generated enum.
• Adoption gating for new icon libraries. Adding a set becomes two explicit steps (install the set, regenerate enums) with a visible blast radius. That gives product a natural checkpoint when marketing asks for "Phosphor on the landing pages" and the legitimate answer may be "we standardize on Heroicons." It converts a silent dependency increase into a decision someone owns.
• Onboarding velocity. New engineers discover the icon catalog through IDE autocomplete instead of a docs site or a Figma lookup. The per-ticket effect is small but applies to nearly every UI ticket — exactly the profile worth funding as a one-sprint DX investment.
• Filament upgrade planning. Release 1.1.0 adds Filament v5 to a documented compatibility matrix — a genuine positive signal for a young package. But the 1.0.1 → 1.1.0 line appears to jump from v3-era to v5, so confirm whether v4 is supported or stranded before this becomes the thing blocking a framework upgrade.
• A test case for how the team treats small utility dependencies generally. Zero stars, zero dependents, single maintainer: no independent production validation. The 1.1.0 release and published matrix are real signals, but they do not change the profile. The pilot is the decision.

When to Consider This Package

Consider it when:

• The product is a Filament app (or Laravel + Blade Icons) on PHP 8.1+ — the package emits enums, so nothing works below 8.1.
• You can verify your Filament version against the documented compatibility matrix. This now requires an actual check rather than an assumption; a forward-only support line would strand existing estates on 1.0.1.
• You have more than one icon set installed, or a credible plan to add one. The payoff scales with catalog size and churn — a single small set on one panel is marginal.
• Icons are a brand or design-system concern with an approvable list, or the admin UI is customer-visible (white-label, embedded admin, per-tenant theming). This is where governance has real value.
• You want a bounded, time-boxed pilot: one panel, committed enums under your own namespace, a pinned version, an explicit exit criterion. The low exit cost makes this sensible.
• The team has or will build a CI drift gate. "No dry-run mode" is a known gap, not a pending fix — the workaround is five lines of CI, but someone must own writing them.

Look elsewhere (or defer) when:

• You are on a Filament version outside the supported matrix, or you're mid-upgrade and don't want a second variable in that debugging session.
• The requirement is a runtime searchable icon picker that lets admins choose and store an icon string. The package summary pitches exactly this, but the README and release notes are entirely about enum generation. Verify against php artisan list and the generated files before planning any UI around a picker — this discrepancy is the single most important thing to resolve before a stakeholder sees a demo.
• You need design-system tooling that is independently validated, vendor-supported, or has an SLA. Zero dependents means you are the first production user in any meaningful sense.
• The team will not commit to regeneration discipline. A stale enum is worse than a raw string, because it type-checks while pointing at icons that no longer render.
• You install a very large catalog (Font Awesome is thousands of cases) and would flood IDE indexing and autocomplete. Scope the config, or don't adopt.
• The estate is large enough that standardizing on a single-maintainer package is a real continuity risk with no fallback plan written down.

Defer until you've answered three questions in a spike: does a generated enum case work directly in ->icon() (or does it need ->value)? Is the picker field real? Are enums namespaced per set so two sets can coexist? Each answer changes call-site design across the whole app.

How to Pitch It (Stakeholders)

To executives — one paragraph: Our admin UI picks icons from raw strings today, which means a missing or renamed icon ships as a blank square and nobody finds out until a customer does. This package, which we already have the icon libraries for, turns that into typed, reviewable code — removing an icon becomes a build error instead of a production defect. Integration is under a day, the output is code we own and can generate ourselves if we ever drop the dependency, and the realistic worst case is we delete one line and one Artisan command. I'm asking for a time-boxed pilot on a single panel, not a standardization decision. The caveat: it's a young, single-maintainer package with no other known users, which is precisely why the pilot is scoped and reversible.

To engineering — the summary: Treat it as codegen, not a runtime dependency. Install it as a dev dependency, generate plain PHP enums into our namespace, commit them, and regenerate deliberately after any icon-set update. The package does nothing at runtime; the enums are ours. That gives us the low exit cost.

Three things to sequence correctly and one to decide:

1. Verify the Filament version matrix before installing. 1.1.0 targets v5; confirm where we sit.
2. Confirm the generated API surface. Whether ->icon(Heroicon::UserCircle) works directly or needs ->value determines every call site — answer it in the first ten minutes, not after twenty tables are written.
3. Deploy order is generate → icons:cache → serve. A stale icon cache presents as blanks and wrong glyphs even when everything is correct. Add it to the runbook, and bump this package and regenerate in the same commit as any Filament upgrade.
4. Decide: raw generated enum, or a curated wrapper enum of approved icons? I'd argue for the wrapper. It caps blast radius on icon-set churn, makes off-catalog icons visible in PRs, and is the seam that makes per-tenant icon sets a config change later. Retrofitting it after the call sites exist is painful.

Two known gaps we own, not bugs we wait on: there is no dry-run mode, so we build a CI drift check (regenerate, git diff --exit-code, fail on change) — without it a stale enum type-checks while pointing at icons that no longer exist. And the package description advertises a searchable icon picker while the release notes describe enum generation; verify which we actually get before anyone plans UI around it. Finally, add a small test asserting the cases we reference exist, so an upstream rename fails CI instead of rendering a silent blank.

To design/brand (if applicable): this is where the approved icon list becomes enforceable rather than advisory. Give us the sanctioned set once, we encode it as a wrapper enum, and unauthorized icons stop appearing in the product — reviewed in code, not caught in QA.