Filament Icons Laravel Package

Getting Started

Minimal Setup

1. Install Core Package

   composer require filafly/filament-icons
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="Filafly\FilamentIcons\FilamentIconsServiceProvider" --tag="filament-icons-config"
   

3. Choose an Icon Set Install one of the official/community packages (e.g., Phosphor):

   composer require filafly/filament-phosphor-icons
   

4. Configure Default Driver Update config/filament-icons.php:

   'default' => 'phosphor',
   

First Use Case: Replacing Default Icons

Replace Filament’s Heroicons in a widget or page:

use Filafly\FilamentIcons\Facades\FilamentIcons;

FilamentIcons::set('heroicon-o-chart-bar', 'heroicon-o-chart-bar-solid'); // Override
FilamentIcons::set('heroicon-o-chart-bar', 'phosphor-chart-bar'); // Switch to Phosphor

Implementation Patterns

Core Workflows

1. Global Icon Overrides Set defaults in config/filament-icons.php:

   'aliases' => [
       'heroicon-o-chart-bar' => 'phosphor-chart-bar',
   ],
   

2. Dynamic Icon Switching Use in Blade:

   <x-dynamic-icon :name="$iconName" :style="$iconStyle" />
   

   Or in PHP:

   FilamentIcons::get('heroicon-o-chart-bar', 'solid');
   

3. Component-Level Overrides Extend a Filament component:

   use Filafly\FilamentIcons\Concerns\HasFilamentIcons;
   
   class MyWidget extends Widget implements HasFilamentIcons {
       protected static string $icon = 'heroicon-o-chart-bar';
   
       public function icon(): string {
           return FilamentIcons::get($this->icon, 'solid');
       }
   }
   

4. Style Variations Pass styles dynamically:

   FilamentIcons::get('phosphor-chart-bar', 'fill'); // Phosphor-specific style
   FilamentIcons::get('heroicon-o-chart-bar', 'outline'); // Heroicon style
   

Integration Tips

• Blade Directives Register a directive for shorthand:

  Blade::directive('icon', function ($name) {
      return "<?php echo FilamentIcons::get($name); ?>";
  });
  

  Usage:

  @icon('phosphor-chart-bar')
  

• Resource Icons Override resource icons in getHeaderActions() or getHeader():

  public static function getHeaderActions(): array {
      return [
          FilamentIcons::get('heroicon-o-cog') => MyAction::make(),
      ];
  }
  

• Theme Switching Use middleware to change icon sets per theme:

  public function handle(Request $request, Closure $next) {
      FilamentIcons::setDriver('dark' === $request->theme ? 'phosphor-light' : 'phosphor');
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Style Mismatches

   • Issue: Phosphor’s fill style may not align with Heroicon’s outline.
   • Fix: Test styles in isolation or use a style mapper:

     FilamentIcons::mapStyle('outline', 'phosphor', 'regular');
     

2. Caching Headaches

   • Issue: Icon changes may not reflect due to Blade caching.
   • Fix: Clear views or use php artisan view:clear.

3. Missing Icons

   • Issue: Custom icon sets may lack certain Heroicon aliases.
   • Fix: Extend the set or create a partial alias:

     FilamentIcons::alias('heroicon-o-chart-bar', 'phosphor-chart-bar');
     

4. Dependency Conflicts

   • Issue: Icon libraries (e.g., Font Awesome) may conflict with existing assets.
   • Fix: Use @vite or @asset directives to scope CSS/JS.

Debugging

• Log Icon Resolution Enable debug mode in config:

  'debug' => env('FILAMENT_ICONS_DEBUG', false),
  

  Check logs for resolved icons and styles.

• Inspect Rendered HTML Use browser dev tools to verify icon classes (e.g., i-phosphor-chart-bar).

Extension Points

1. Custom Drivers Implement Filafly\FilamentIcons\Contracts\IconDriver:

   class MyIconDriver implements IconDriver {
       public function get($name, $style = null) {
           return "my-icon-{$name}-{$style}";
       }
   }
   

   Register via config:

   'drivers' => [
       'my-icons' => \App\Providers\MyIconDriver::class,
   ],
   

2. Dynamic Style Mapping Override style resolution:

   FilamentIcons::mapStyle('outline', 'phosphor', 'bold');
   

3. Icon Fallbacks Set fallbacks for missing icons:

   FilamentIcons::fallback('heroicon-o-chart-bar', 'heroicon-o-chart-bar-solid');
   

Pro Tips

• Icon Consistency Use a IconRegistry trait to centralize icon definitions:

  trait IconRegistry {
      protected static array $icons = [
          'dashboard' => 'phosphor-house',
          'settings' => 'phosphor-gear',
      ];
  }
  

• Dark Mode Icons Leverage style variations for dark mode:

  FilamentIcons::get('phosphor-moon', request()->darkMode ? 'fill' : 'regular');
  

• Performance Preload icon fonts in app.blade.php:

  @if (FilamentIcons::hasDriver('phosphor'))
      <link rel="preload" href="{{ asset('vendor/phosphor-icons/phosphor.css') }}" as="style">
  @endif