Filament Iconoir Icons Laravel Package

Getting Started

1. Confirm compatibility before installing. The v2.1.0 release adds Filament 5 support while keeping Filament 4 compatibility, so first check the package’s composer.json constraints against your app’s filament/filament and Laravel versions. If you are still on Filament 4, you should not need to change your application code just to adopt this release.
2. Install or upgrade through Composer.

   composer require <vendor>/<package>:"^2.1"
   

   For an existing install:

   composer update <vendor>/<package> --with-dependencies
   

3. Look first at the package README and service provider. The most important integration point is usually how the package registers itself with a Filament panel. Check for a plugin class, a service provider, or documented panel-provider registration.
4. Register the plugin with your Filament panel. A typical Filament plugin integration looks like:

   use Vendor\Package\PackagePlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               PackagePlugin::make(),
           ]);
   }
   

   Use the package’s documented class name and configuration method; do not assume the API from this release note alone.
5. Publish configuration or assets only if documented.

   php artisan vendor:publish --tag=<package-config>
   php artisan vendor:publish --tag=<package-assets>
   

6. First use case: register the plugin in a single Filament panel, run php artisan optimize:clear, and verify the package’s resources, pages, widgets, or actions appear in the panel. This gives you a quick signal that Filament 5 detection and panel bootstrapping are working.

Implementation Patterns

• Panel-scoped registration. Register the package plugin only in the Filament panels that need it. For multi-panel applications, this keeps admin, tenant, or customer-facing panels isolated:

  ->plugins([
      PackagePlugin::make()
          ->tenantAware(),
  ])
  

  Check the package docs for the actual fluent methods before using them.
• Version-aware dependency management. Because v2.1.0 supports both Filament 4 and 5, pin the package to ^2.1 and let Composer resolve the appropriate Filament version. Avoid manually forcing Filament 5 in an app that still depends on Filament 4 APIs.
• Upgrade in a branch or staging environment. Run the package test suite, then exercise the panel manually. Filament major versions can change method signatures, asset behavior, and navigation APIs even when the package declares compatibility.
• Use the package’s service provider hooks for application-specific behaviour. Common extension points include config files, policy registration, navigation group customization, and publishing migrations. Prefer these over editing vendor files.
• Test both panel boot and package features. A package can install cleanly but fail when a panel boots. At minimum, assert that the panel provider resolves, the plugin registers, and any package routes or Livewire components render.
• Keep Filament panel configuration centralized. If you register the package in several panels, extract shared plugin configuration into a dedicated method or config file to avoid drift between Filament 4 and 5 environments.
• CI matrix for dual compatibility. If your application or downstream packages support both Filament versions, test against Filament 4 and Filament 5 dependency sets. This is especially relevant for packages that extend this package or override its Filament components.

Gotchas and Tips

• “Supports Filament 5” does not mean every feature behaves identically. The release note confirms compatibility, but Filament 5 may introduce deprecations or changed defaults. Check the package changelog and Filament upgrade guide for behavioural differences.
• Watch Composer resolution conflicts. If another package pins Filament 4, Composer may keep you on Filament 4 even after updating this package. Run composer why-not filament/filament "^5.0" to diagnose.
• Clear Filament and Laravel caches after upgrading.

  php artisan optimize:clear
  php artisan filament:cache-components
  

  Use the package’s documented cache commands if it provides any.
• Check asset publishing after a Filament major upgrade. Filament 5 may expect updated assets or CSS. If the panel renders but styles or scripts are missing, republish the package’s assets and rebuild frontend assets if applicable.
• Do not assume the plugin class name or namespace. The release note does not document registration details. Confirm against the package README or source before wiring it into a panel provider.
• Review migrations before running them. If the package publishes migrations, inspect them for Filament 5-specific schema changes or new columns before php artisan migrate.
• Debug panel boot failures with verbose logging. If the plugin causes a blank panel or container exception, check storage/logs/laravel.log, then temporarily remove the plugin from the panel provider to isolate whether the issue is package registration or a downstream Filament API change.
• Prefer explicit version constraints in application code. Use ^2.1 for the package, and constrain Filament according to your application’s actual support policy rather than allowing an accidental major upgrade.
• Extension point caution: if you subclass package Filament resources or override package views, re-test those overrides against Filament 5. Compatibility at the package level does not guarantee compatibility of your local overrides.