Filament Carbon Icons Laravel Package

Getting Started

Start by checking the package's composer.json before anything else — the headline change here is a widened Filament constraint (^4.0|^5.0), so confirm what your app currently resolves to and whether the package ships a single codebase or version-gated branches for the two majors. That constraint is your first compatibility signal.

Minimal install:

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-config   # if the tag exists

The package relies on Laravel's package auto-discovery for its service provider, so there should be nothing to register in config/app.php. The real registration step is in your Filament panel provider:

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(\Vendor\Package\PackagePlugin::make());
}

Where to look first: the package's own test suite and CI matrix. A release that claims simultaneous Filament 4 and 5 support is only credible if there is a build matrix proving it — a testbench/orchestra setup running against both filament/filament:^4.0 and ^5.0. If that matrix exists, you can trust the release note; if it doesn't, treat the claim as aspirational and smoke-test yourself.

First use case: register the plugin on a non-production panel, load a resource or page the plugin touches, and confirm assets resolve. Filament plugin breakage almost always surfaces as a missing asset, a 500 on the panel route, or a silently unregistered component — not as a Composer error.

Implementation Patterns

Pin the Filament major per environment. Because the package now spans two majors, keep the version decision in your root composer.json rather than letting the package's constraint decide. On a fresh project run composer require filament/filament:^5.0 explicitly; on an existing app, run composer why filament/filament after installing the package to confirm you didn't get silently upgraded.

Staged rollout across the majors. The normal workflow is: upgrade the package within your existing Filament 4 app first (composer update <vendor>/<package> — the widened constraint should be a no-op for you), verify nothing regressed, then plan the Filament 5 upgrade as a separate change. Doing both in one commit makes bisecting failures impossible.

Panel-scoped registration. Register the plugin only on the panels that need it. Filament's plugin system is per-panel, so multi-panel apps (admin, staff, customer) can adopt the package incrementally — useful while you validate Filament 5 behaviour on the least critical panel.

Config over code. Publish the config file and drive behaviour from there rather than subclassing package classes. Anything the package exposes via config survives a major version bump; anything you subclass is a private API you now own.

Wrap any version-conditional extension points. If you extend the package's resources, pages, or form/table schema classes, isolate that code behind your own base classes so a Filament 5 signature change is a one-file fix rather than a grep across the app.

Lockstep with your upgrade tooling. If you use Laravel Shift, Rector, or Filament's own upgrade guide, sequence the Filament 5 jump and the package bump together — the package's dual support means it is not the blocker, your own customisations are.

Gotchas and Tips

• The dual constraint is not a guarantee. ^4.0|^5.0 means the package installs against both; it does not mean every code path is exercised in both. Check whether CI runs the full matrix or just a resolve-only check on the older major.
• Filament 5 API drift is the likely failure mode. Between Filament majors, schema/form/table namespaces and method signatures shift. Errors typically appear as BadMethodCallException, Class not found, or a silently empty form rather than a hard crash. If a page renders but the widget is blank, suspect a renamed fluent method.
• Asset and view publishing goes stale. Re-publish after the upgrade, or at minimum clear public/vendor/<package> and re-run filament:assets. Custom published views are the single most common source of "it upgraded but looks wrong."
• Tailwind content paths. If you publish views, your tailwind.config.js content globs must still match wherever the package now stores its views — a directory move in the package silently strips styles.
• Clear the caches, always. php artisan filament:optimize-clear && php artisan optimize:clear before debugging. Panel registration is cached; a plugin that "won't appear" is usually a stale bootstrap/cache entry or a cached config.php.
• Livewire compatibility. Filament 5 pins a newer Livewire range. If another package in your app constrains Livewire, Composer will resolve to Filament 4 without telling you. Check composer show livewire/livewire after the update.
• Debugging registration. Use php artisan about and inspect the panel's resolved plugins via tinker (Filament::getPanel('admin')->getPlugins()) to confirm the plugin actually attached — faster than guessing from the UI.
• Report issues with the major stated. When filing upstream, say which Filament major reproduced the bug. With dual support, maintainers will ask first thing, and "both" vs "only 5" changes the fix entirely.