Filament Icons Laravel Package

Getting Started

Verify three things before you type composer require:

1. PHP 8.1+. The entire value proposition is generated enum classes; below 8.1 you get nothing.
2. Filament version against the compatibility matrix. Release 1.1.0 added Filament v5 support and a "version compatibility" section to the README. The 1.0.1 → 1.1.0 jump looks like v3-era straight to v5, so if you're on v4, confirm you're actually supported before you build call sites on top of this. Don't infer from the star count or the description — read the matrix.
3. blade-ui-kit/blade-icons plus at least one concrete icon set (Heroicons, Phosphor, Font Awesome…). The generator enumerates installed sets. It ships no icons of its own, and an empty enumeration produces empty enums.

Install sequence:

composer require guava/filament-icons
php artisan vendor:publish   # pick the filament-icons tag
php artisan list | grep -i icon   # find the generator command name
php artisan icons:cache      # do this immediately, see Gotchas

Read the published config first. It's where you scope which icon sets get enumerated — and that scoping decision has downstream consequences for IDE performance and name collisions.

Where to look first, in order:

• the config file (which sets am I exposing?),
• the generator command's --help (where does it write, what namespace?),
• one generated enum file, opened and eyeballed against the actual icon set.

That third step is not optional. You need to know what a case is before you write a single call site.

First use case — swap one navigation icon. This exercises the whole pipeline (enum exists → autoloads → resolves through the icon cache → renders in the panel) in a single line:

// before
protected static ?string $navigationIcon = 'heroicon-o-cog';

// after
protected static ?string $navigationIcon = Heroicon::Cog;

If the admin panel renders, you're integrated. If it doesn't, you've isolated the problem to caching or namespacing rather than buried inside a Livewire component you haven't written yet. Do this before touching forms, tables, or actions.

One thing to resolve on day one: the package description pitches a searchable icon-picker form field and a matching table column, while the README and release notes are entirely about enum generation. Both may exist, but verify against php artisan list and the actual installed files before you plan UI around a picker. If you need an admin-facing picker that stores a string, confirm that's a real feature here and not a summary borrowed from a different plugin.

Implementation Patterns

Treat it as codegen, not a runtime dependency. Install it as a dev dependency if your policy allows, commit the generated enums under your own namespace, and regenerate deliberately. Nothing in the output should call back into the package — which is precisely what makes the exit cost so low later.

Nail down the generated API surface before designing call sites. The single highest-leverage five minutes of your spike: does each case implement Filament's HasIcon/HasLabel so ->icon(Heroicon::UserCircle) works directly, or do you need ->icon(Heroicon::UserCircle->value) or a closure? That one answer changes every usage site in the codebase. Check it once, write it in the PR description, move on.

Once you know, the enum becomes your typed vocabulary for ->icon(), navigation items, actions, table column icons, and badge icons.

Extract the form-select mapping exactly once. Enum::cases() → [value => label] recurs in every form class. Put a static helper on the enum (or a small shared trait) instead of hand-rolling collect(...)->mapWithKeys(...) in twenty places — otherwise you've only relocated the stringly-typed sprawl:

Select::make('icon')
    ->options(Heroicon::options())   // cached helper, not inline per-form
    ->searchable();

Pick a regeneration policy and write it into the repo.

• Committed output (recommended). Regenerate after any icon-set composer update, review the diff like code, commit it. The diff becomes your changelog: "which icons appeared or disappeared this sprint."
• Generated in CI. Only viable with a drift gate. There's no documented --check or dry-run mode, so build one: run the generator in CI, then git diff --exit-code on the enum directory and fail on any change. Without this gate, a stale enum is worse than a raw string, because it type-checks while pointing at icons that no longer exist.

Curate a wrapper if approved icons are a product concern. Don't let every call site reference the raw generated enum if the design system says twelve icons are approved:

enum ApprovedIcon: string {
    case User = Heroicon::UserCircle->value;
    case Home = Heroicon::Home->value;
    // twelve approved cases, nothing else
}

You keep type safety, bound the blast radius of icon-set churn, and make intent reviewable. Off-catalog icons show up in PRs rather than in QA.

Multi-brand / white-label. Because the case name is symbolic and the concrete set lives in config, per-tenant icon sets become a config change — provided your curated wrapper is the seam and the case names you depend on survive across sets. Design that seam early; it's cheap now and painful to retrofit.

Testing layer. Static analysis (PHPStan/Psalm) is your primary net: a removed case becomes a compile-time error at every reference site. Add a small test asserting the specific cases you reference exist, so an upstream rename fails CI instead of rendering a silent blank in production.

Keep runtime-dynamic icons separate from enums. If admins pick icons through a UI and you persist the choice in a string column, that's legitimate — enums are compile-time. Enums for developer-authored UI (navigation, actions, columns); strings for data-driven icons. Trying to unify the two produces from($string) lookups that defeat the entire point of the package.

Regenerate in the same commit as the icon-set bump. Never let an icon-set composer update land separately from the enum regeneration. Two variables moving independently is how you end up bisecting a blank icon at 5pm.

Gotchas and Tips

The icon cache is the number-one confusing failure mode. A stale Blade Icons cache presents as missing or wrong glyphs even when both the enum and the icon set are perfectly correct. Be precise about ordering in your install runbook and your deploy pipeline: generate → icons:cache → serve. There's no documented way to verify the cache is warm, so your smoke test is "does one known icon render in the admin panel."

Renames are silent; deletions are loud. A removed case breaks compilation — that's the feature working. A renamed icon simply stops resolving and renders a blank square with no error, escaping almost every test you'll write. This is the strongest argument for the CI drift check: if you can't see the diff, you can't see the rename.

Answer the name-collision question before you commit. user, home, settings, and cog exist in essentially every icon set. Confirm whether the generator namespaces per set (Heroicon::Home and Phosphor::Home coexisting) or prefixes case names. Irrelevant with one set installed; immediately relevant the day marketing asks for a second.

Large catalogs hurt your editor. Font Awesome is thousands of cases. A generated enum that size slows IDE indexing and floods autocomplete with noise. Scope the config to the sets you actually use, and expose the curated wrapper rather than the full catalog to call sites.

No dry-run mode means drift detection is yours to own. Treat it as a known gap, not a bug to wait on. The workaround is about five lines of CI.

Upgrade sequencing. When you bump Filament, bump this package and regenerate in the same commit. A Filament major plus a stale enum set is a two-variable debugging problem you don't want on a Friday afternoon.

Documentation drift is a real signal here. The summary promises a searchable picker; the release notes are about enum generation. Verify claims against php artisan list and the generated files, not against the description.

Extension points are limited, so plan around them. The config governs which sets get enumerated; the generated enums are plain PHP. If you need custom behavior — labels, grouped options, filtering — you add it via a trait or wrapper enum on your side. Don't reach into package internals for customization; you'll pay for it on the next minor bump.

Maturity is the caveat, and it's about blast radius, not quality. Zero stars, zero dependents, single maintainer — no independent production validation. Filament v5 support and a published compatibility matrix are genuine positive signals, but they don't change the profile. The mitigation is cheap: commit generated files under your own namespace, pin the package version, and remember the fallback — a hundred-line Artisan command that walks registered icon sets and emits enums — means removing one composer require line and replacing one command. That low exit cost is exactly why a time-boxed pilot on one panel is sensible, while standardizing it across the whole estate is premature.