Phosphor Icon Replacement Laravel Package

Getting Started

Status: deprecated as of v1.0.2. The only change in this release is the deprecation of the package ([FIL-29]). There are no code changes, bug fixes, or features. Do not adopt it for new work.

If you are already on v1.0.1 or earlier

1. Nothing breaks by upgrading to v1.0.2 — it is a metadata-only release. Upgrading simply marks your dependency graph as depending on an abandoned package.
2. Decide deliberately between two paths:
   • Stay pinned to v1.0.1 (or your current lock) while you plan a migration. Pin exactly in composer.json rather than using ^1.0 so a future composer update cannot pull in surprises.
   • Upgrade to v1.0.2 if you want Composer's deprecation/abandonment notice to show up in composer install output and composer audit as a standing reminder for the team.
3. Read composer.json and the package's service provider first — they show what it registers (typically a Filament panel hook plus a published config file). That registration is the entire surface area you need to replace.

First use case (existing installs only)

Publishing the package config and confirming which icon set is currently being swapped is the fastest way to understand your exposure:

php artisan vendor:publish --tag="phosphor-icon-replacement-config"

The published config is the map of what the package controls — treat it as your migration checklist.

For new projects: use Filament's built-in icon configuration (->icons([...]) on the panel, plus per-component icon() overrides) together with a maintained Phosphor icon set such as codeat3/blade-phosphor-icons, which exposes icons as Blade components and is usable directly in Filament navigation, resources, and actions.

Implementation Patterns

Because the package is deprecated, the useful patterns are migration patterns rather than usage patterns.

1. Inventory the swap points

Grep your application for anything the package provides or overrides:

grep -rn "Phosphor\|phosphor" app/ config/ resources/

If the package transparently replaced the default icon set, most references will not be in your code — they will be implicit in every Filament resource and page using the default. That is the real scope of the migration, and it is why an early start matters.

2. Replace globally first, then per-component

Set the panel-level icon configuration to a maintained Phosphor set. Anything rendered without an explicit icon() will pick this up, which covers the bulk of your UI in one change:

// app/Providers/Filament/AdminPanelProvider.php
$panel->icons([
    'panels::sidebar.group' => 'phosphor-squares-four',
    'panels::topbar'        => 'phosphor-list',
    // ...
]);

Then handle explicit overrides: navigation groups, resources, pages, actions, and widgets that pass a string or a Heroicon enum. Heroicon::OutlinedXMark-style enum usages must be converted to a string icon name or the equivalent Blade component, since enums are type-checked by Filament.

3. Move the mapping into config, not code

Keep a single PHP array (or a config/icons.php) mapping semantic names to Phosphor names, and reference it from the panel provider. When you adopt the next icon library, you edit one file instead of hunting through resources.

4. Run a side-by-side comparison

Before removing the package, render a few pages with both configurations in a branch and diff screenshots. Icon swaps are visually silent failures — a name that does not resolve renders nothing rather than throwing, so eyeballing is the only reliable check.

5. Remove in one clean commit

Once the panel config and all overrides are in place:

composer remove filafly/phosphor-icon-replacement

Then delete any published config file, and commit the lockfile change separately so the composer audit delta is easy to review.

Gotchas and Tips

• Deprecation is usually a metadata flag, not a runtime error. The package will keep working. The risk is the absence of future fixes — particularly if a later Filament major bumps the icon API, this package will not follow, and you will be stuck on an old Filament.
• Composer will now warn on install/update. If the package is marked abandoned on Packagist, composer install, composer update, and composer audit all surface it. Expect CI noise if you gate on audit output, and budget for the migration rather than disabling the check.
• Pinning ^1.0 is a trap in both directions. It allows future 1.x releases from an unmaintained repo. Prefer an exact constraint ("filafly/phosphor-icon-replacement": "1.0.1") if you are staying, or drop the dependency entirely.
• Unresolved icon names fail silently. Filament renders an empty SVG or nothing at all for an unknown icon string — no exception, no log entry. When migrating, verify by DOM inspection (<svg> present, correct path count) rather than by trusting the layout. Filament's icon caching is also a common culprit: clear it with php artisan filament:clear-cached-components and php artisan icons:clear if your icon set ships a cache.
• Enum vs. string icons. Filament 3 accepts both Heroicon enums and plain strings. The package almost certainly supplies strings only. Anywhere your own code passes an enum (common in actions and forms), you must convert it, since the enum will continue to resolve to a Heroicon regardless of your panel's icon config.
• Check custom pages and Blade views separately. Panel icon configuration does not touch icons hardcoded in Blade (<x-heroicon-o-...>). Those are outside the package's reach and outside your config migration — grep resources/views explicitly.
• Extension points, if you must fork. The package is small (a service provider, a config, and an icon mapping). If you need to keep Phosphor without the dependency, the fastest safe path is to vendor the mapping array into your own config and register it in your panel provider — a few dozen lines, no provider package required. Do this under a name your team owns so nobody mistakes it for the upstream package.
• Record the decision. Add a short note to your repo (or an ADR) stating when the package was deprecated, what replacement you chose, and the follow-up ticket. Deprecated dependencies tend to be rediscovered months later by whoever runs the next audit.