Filament Phosphor Icons Laravel Package

Technical Evaluation

Architecture fit

• The package is a leaf dependency with essentially no runtime behaviour: a PHP enum (ToneGabes\Filament\Icons\Enums\Phosphor) mapping Phosphor icon names onto Filament's existing icon contract, plus a companion Weight enum and fluent helpers (->fill(), ->bold(), ->forceWeight()). There is no service provider surface worth reasoning about, no middleware, no published assets in the README, no migrations, no JS build step.
• It fits because it piggybacks on a contract Filament already owns (->icon(), ->onIcon(), ->offIcon(), <x-filament::badge :icon="...">). We are not introducing a new rendering path; we are substituting a name source. That is the lowest-risk shape a dependency can take.
• The design deliberately makes icon choice a named, typed reference (Phosphor::StarBold) rather than a string. For a TPM this matters beyond aesthetics: a mistyped or renamed icon fails in development instead of rendering as an empty box in a customer-facing admin.
• The Weight enum plus forceWeight() converts emphasis from per-component CSS into a declarable convention — primary = bold, active = fill, decorative = duotone. That is reviewable in a PR; a CSS override is not.
• The phosphor:sync artisan command (--dry-run, --enum-path) is the most architecturally significant feature. It reframes the catalogue as generated data we can refresh on our own schedule, not logic we depend on the maintainer to ship. That is what makes a 5-star, single-maintainer dependency defensible here.

Integration feasibility

• Install is composer require tonegabes/filament-phosphor-icons. Adoption work is import swaps plus a design decision — no infrastructure, no credentials, no config publish step described.
• Blade and SVG usage (@svg(Phosphor::Star->getLabel()), svg(...), <x-icon name="...">) is a strong signal of a transitive dependency on a Blade icon registry (the README's sync description explicitly says "from Blade icons," and getLabel() is documented to return a phosphor- prefixed name). Whether that registry ships as a Composer requirement or must be added separately is unconfirmed in the README and is the single most important thing to verify before committing to an estimate.
• Overall, feasible inside a single sprint with one engineer; the risk is concentrated in verification, not in construction.

Technical risk

• Single maintainer, 5 stars, 0 dependents, no stated cadence. There is no community evidence of this package working in production anywhere. The 1.3.1 release notes are a bot-generated "New Contributors" line; 1.4.1's changelog is two bare compare links. We should assume no changelog discipline and diff composer.json and the enum ourselves on every upgrade.
• Filament major-version coupling is the primary ongoing exposure. 1.3.0 added Filament 5 support; that release lag is the pattern to expect at every future Filament major. We are one Filament upgrade away from a blocked framework upgrade path or a forced fork.
• The sync command mutates files inside the package. By default it writes to the enum in vendor/, which Composer will overwrite on reinstall or composer update. Any workflow that relies on a synced enum must pin --enum-path to a first-party location or treat the fork as the source of truth. This is a footgun a TPM should name explicitly in the runbook.
• Catalogue size is an unquantified operational cost. Phosphor is a large set and the README advertises the full catalogue plus per-weight list helpers — plausibly thousands of enum cases. Opcache memory per FPM worker and IDE autocomplete noise are real but likely minor; we should measure rather than assume, and reject any claim that it is free.
• Thin test surface. Nothing in the supplied material indicates a test suite. Our mitigation is our own smoke test over icon call sites, not theirs.
• Security posture is genuinely low. No network calls, no deserialization of untrusted input, no database. The only write path is an artisan command that should never run in production.

Key questions

1. Does Phosphor implement Filament's icon/label contract directly, or does it depend on getLabel() being resolved by a specific Blade icon package? What exactly does composer require pull in?
2. What are the declared composer.json constraints on filament/filament, php, and laravel/framework — and does it accept ^4.0 || ^5.0, or a narrower range that will fight our lockfile?
3. How many enum cases ship, and what is the file size? Does it ship one case per icon-weight combination or one case per icon with weight applied at render?
4. Is there any test suite, CI, or static analysis in the repo? What is the actual commit cadence behind the release dates?
5. Does the enum include only Phosphor, or does it also assume a Heroicons/Blade-icons default remains registered as a fallback?
6. What is the stated (or de facto) process when Phosphor renames or removes an icon — does a case disappear and break our call sites at parse time?

Integration Approach

Stack fit

• Requires Filament 4 or 5 and a modern PHP/Laravel. It is a leaf node: nothing depends on it, it depends only on Filament and whatever icon registry backs getLabel(). That means it can be added and removed without touching our domain code, as long as icon references are isolated.
• It is a Filament-shaped artifact. It offers zero value outside Filament admin surfaces, so scope the rollout to admin only and do not attempt to reuse it in marketing pages or customer-facing front ends without a separate decision.

Migration path

• Coexistence, not cutover. Filament's Heroicons default keeps working. Nothing forces a big-bang swap; icons can be migrated surface by surface (resource tables first, then forms, then navigation, then notifications and empty states), with mixed icon languages visible in the interim.
• Recommended: a one-file internal seam. Wrap Phosphor behind our own thin App\Enums\Icon (or a small facade) and reference that everywhere. This costs a few hours and converts the worst-case scenario from "surgical find-and-replace across the admin" into "rewrite one file" — which is the exit plan made real.
• Sequencing:
  1. Verify the key questions above on a throwaway branch (constraints, dependency tree, enum size, sync behaviour). Half a day.
  2. Decide the icon language and weight convention with design — an hour, and the real cost of the Weight capability. Record it.
  3. Pilot one page. Install, build the seam, convert one resource screen, validate light/dark rendering, validate the toggle on/off pair pattern (StarFill / Star) and an IconColumn boolean.
  4. Roll out resource by resource, converting imports mechanically. Two to three days.
  5. Codify: a review-checklist rule that icon-only actions carry a tooltip or aria-label, and that an icon is never the sole carrier of meaning in a status column. Cheap now, expensive to retrofit.
  6. Document the exit: pin the version, note the fork path, note that phosphor:sync must target our own enum, not vendor/.
• Budget: roughly one day to pilot, two to three more to roll out. The remainder is mechanical.

Compatibility

• Pin the version explicitly (~1.4.1 or exact) and treat any bump as a reviewed change, not an auto-merge. Renovate/Dependabot should be configured to require human review on this package.
• Add a CI gate: an integration test that boots a Filament panel and renders one action, one form field, and one icon column. This catches both Filament-major breakage and any missing icon-registry dependency — the two failure modes that would otherwise surface as blank icons in production.
• Watch the Filament upgrade runbook. When we move to the next Filament major, this package's matching release is a hard prerequisite; if it does not exist, we execute the fork plan rather than delay the framework upgrade.
• Do not couple to getIcons() / getBoldIcons() filtering helpers for product behaviour — those are introspection utilities. Using them to populate a dynamic icon picker is fine; depending on them for rendering is not.

Operational Impact

Maintenance

• Treat this as vendored code, not a supported dependency. MIT license makes that legitimate. The realistic maintenance load is: review composer.json and enum diffs on upgrade (minutes), re-run our smoke test (minutes), and re-run phosphor:sync against our own enum path when Phosphor ships new icons we need (minutes).
• The --enum-path capability is the operational keystone. Configure it to write to a first-party path from day one; leaving the default (writing into vendor/) guarantees a confusing regression the next time someone runs composer install.
• Restrict phosphor:sync to local and CI environments. It writes to the filesystem and has no business running against production.

Support

• No SLA, no security programme, no advisory process, no stated cadence. If policy requires a supported vendor for customer-facing surfaces, this fails that bar and the correct alternative is to inline the generated enum — a few hundred to a few thousand generated lines we own outright.
• Practical support model: we support it. One engineer owns it; the fork is the escalation path. This should be stated in the decision record rather than left implicit.
• Genuine upside: the dependency has no network, no storage, and no external service. Its blast radius if abandoned is stale icon coverage, not outage. That is the argument that makes the low-assurance posture acceptable.

Scaling

• Runtime scaling is a non-issue for typical admin traffic — the class loads once per worker. The measurable cost is opcache memory per FPM worker times worker count, which is worth a five-minute measurement if we run a wide fleet, and negligible if we do not.
• Scaling in the sense that actually matters here is breadth of adoption: every additional admin surface using the enum increases the cost of a swap-out. The internal seam contains that; without it, growth quietly converts a tactical choice into a migration.
• The full catalogue (not a curated subset) is exposed. If admin bundle weight becomes a tracked metric, curation pushes us back into maintaining our own list — at which point we should reassess whether the package is earning its place.

Failure modes

• The dominant theme is that failures are loud and shallow — blank icons or a parse-time fatal, not corrupted data or a security incident. That is the right risk shape for a package we are prepared to take on speculatively.

Ramp-up

• Engineering: under an hour. The API is Phosphor::CaseName plus a handful of fluent helpers; the only new concept is Weight as a convention rather than a style. IDE autocomplete across a very large enum is the one papercut — engineers will want the design's icon map or the Phosphor website open.
• Design: roughly an hour of agreement to fix the weight convention and the icon-to-surface mapping. This is the real cost of the package and should be scheduled, not assumed.
• QA: minimal and mechanical — verify light/dark rendering, verify toggle state pairs, verify icon-only actions carry accessible labels. One pass per converted surface.
• Total to first value: one pilot day. Total to done: three to four days of engineer time plus one design hour, with the accessibility rule decided up front rather than retrofitted across a shipped admin.