Filament Hugeicons Icons Laravel Package

Getting Started

This release is a compatibility bump: the package now runs on Filament 5 while still supporting Filament 4. There is no migration work if you are already on Filament 4 — install/upgrade as usual and pin your Filament constraint.

Minimum steps:

1. composer require <vendor>/<package>:"^1.1" (or composer update <vendor>/<package> if already installed).
2. Confirm your filament/filament constraint matches the major you intend (^4.0 or ^5.0). The package resolves against both, so Composer may otherwise leave you on whichever your lockfile already had.
3. Register the plugin in your panel provider — for Filament v4/v5 this is typically ->plugin(YourPlugin::make()) inside Panel::make()->plugins([...]) (or the ->plugin() fluent call depending on the package's registration style).
4. Publish config/assets only if you need to customise: php artisan vendor:publish --tag=<package>-config. Skip this initially so future package defaults reach you.
5. Run php artisan filament:optimize (or clear caches via php artisan optimize:clear) and load a panel page to confirm assets register.

Where to look first:

• The package's README install section for the exact plugin registration snippet for your Filament major — v4 and v5 panel APIs are close but not identical.
• composer show <vendor>/<package> to verify the resolved version and that only one Filament major is installed.
• The package's src/ service provider to see what it registers (panels, views, migrations, commands) before you assume behaviour.

First use case: drop the plugin into one non-critical panel, verify the resource/page renders, then roll to your primary admin panel.

Implementation Patterns

Version-agnostic panel registration. Keep plugin registration in a dedicated provider or a small Panel::configure() call so the same code path works on Filament 4 and 5. Avoid branching on Filament version unless the package documents an API divergence.

Feature-flag the rollout per panel. If you run multiple panels, register the plugin per panel rather than globally. This lets you validate Filament 5 behaviour on an internal panel before exposing it to customer-facing admin surfaces.

CI matrix across both majors. Since the package claims 4 and 5 compatibility, test your app on both if you support both. A job matrix with filament/filament:^4.0 and ^5.0 will catch transitive breakage early — this is cheap insurance for a plugin that now straddles two majors.

Lockstep upgrade sequencing. Upgrade Filament first, then the package, then any sibling plugins. Filament plugins often share contracts and asset registration; upgrading out of order produces confusing "class not found" or duplicate-asset symptoms that look like package bugs.

Configuration over forking. Most behavioural knobs (navigation labels, visibility, default page options) live in the published config or the plugin's fluent builder. Use those before subclassing package classes — subclasses are the first thing to break on a major bump.

Wrap third-party plugins behind a thin adapter if you call their classes directly from your own resources. When Filament 6 lands, you change one adapter rather than every call site.

Gotchas and Tips

• Composer may silently keep you on Filament 4. Because the package supports both majors, composer update will not force Filament 5. Check composer show filament/filament after upgrading — this is the single most common "the new feature isn't working" cause.
• Duplicate Filament majors. A stale lockfile can end up with both filament/filament v4 and v5 in the vendor tree via different constraints. composer why filament/filament and a clean composer update --with-all-dependencies resolves it.
• Asset registration differs subtly between majors. If styles or scripts vanish after upgrading, re-run php artisan filament:assets and clear the view cache; do not start debugging the package until you have done both.
• Panel provider caching. Filament caches panel configuration in production. Deploying the new version without php artisan optimize:clear (or filament:optimize) leaves the old plugin list in place.
• No deprecations were announced, but "maintains Filament 4 compatibility" is a statement of intent, not a contract. Treat any use of package classes/interfaces beyond the documented plugin API as internal and re-verify on each minor release.
• Check the changelog cadence. This is a single-line minor release. That is fine for a compatibility bump, but it means the maintainer's compatibility testing surface is now doubled — watch the issue tracker for Filament-5-specific reports in the weeks after release before making it a hard dependency of a critical panel.
• Extension points: the plugin builder (YourPlugin::make()->...) and the published config are the supported customisation surfaces. Prefer them over service-container rebinding of package classes, which will not survive the next major.
• Debugging tip: when something renders wrong, first disable all other plugins on the panel. Filament plugin interactions (asset ordering, navigation collisions) produce symptoms that mimic the newest plugin's bugs.