Filament Phosphor Icons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require filafly/filament-phosphor-icons
   

2. Register the plugin in your PanelProvider:

   use Filafly\Icons\Phosphor\PhosphorIcons;
   
   public function panel(Panel $panel): Panel {
       return $panel->plugin(PhosphorIcons::make());
   }
   

3. First use case: Replace default Filament icons in your first widget/page:

   Icon::make('heroicon-o-cog-6-tooth')->size(24)
   

   Now uses Phosphor’s equivalent (e.g., Phosphor::Cog).

Where to Look First

• Icon Reference: Phosphor Icons (official docs).
• Filament Icon Aliases: Filament Docs for mapping legacy icons.
• Package Config: Check config/filament-phosphor-icons.php for global defaults.

Implementation Patterns

1. Global Icon Style Management

• Default: Regular style (consistent with Filament’s aesthetic).
• Override globally in PanelProvider:

  PhosphorIcons::make()->bold()->duotone();
  

• Per-page override: Use middleware or service provider to dynamically set styles.

2. Icon Usage Patterns

Basic Usage

// Direct enum usage (recommended for clarity)
Icon::make(Phosphor::Cog)->size(20);

// Alias mapping (for legacy Filament icons)
Icon::make('heroicon-o-cog-6-tooth')->size(20); // Auto-mapped to Phosphor::Cog

Dynamic Icons

// Conditional rendering with Phosphor
$icon = $record->isActive ? Phosphor::CheckCircle : Phosphor::XCircle;
Icon::make($icon)->color($record->isActive ? 'success' : 'danger');

Custom Icon Sets

// Group related icons (e.g., for a dashboard)
$dashboardIcons = [
    Phosphor::House,
    Phosphor::ChartBar,
    Phosphor::Users,
];

3. Integration with Filament Components

Widgets

use Filament\Widgets\Widget;

class StatsOverview extends Widget {
    protected static string $view = 'widgets.stats-overview';

    public function getIcon(): string {
        return Phosphor::Gauge; // Uses Phosphor enum
    }
}

Forms/Tables

// Table columns
Table::make()
    ->columns([
        Tables\Columns\IconColumn::make('status')
            ->icon(fn ($record) => $record->isActive ? Phosphor::Check : Phosphor::X),
    ]);

// Form buttons
Buttons\Action::make('edit')
    ->icon(Phosphor::PencilSimple)
    ->color('primary');

4. Theming with Styles

• Per-Icon Overrides:

  PhosphorIcons::make()
      ->regular() // Global
      ->overrideStyleForAlias('heroicon-o-cog-6-tooth', PhosphorIcons::STYLE_BOLD);
  

• Dynamic Style Switching:

  // In a view
  @php
      $iconStyle = request()->get('icon_style', 'regular');
      PhosphorIcons::setStyle($iconStyle);
  @endphp
  

Gotchas and Tips

Pitfalls

1. Alias Mismatches:

   • Not all Filament aliases map 1:1 to Phosphor. Verify with:

     php artisan vendor:publish --tag="filament-phosphor-icons-config"
     

     Then check config/filament-phosphor-icons.php for mappings.

2. Style Inconsistencies:

   • Some styles (e.g., duotone) may clash with Filament’s default colors. Test in isolation:

     Icon::make(Phosphor::AlertCircle)->style(PhosphorIcons::STYLE_DUOTONE)->color('warning');
     

3. Caching Issues:

   • Clear Filament’s view cache after style changes:

     php artisan filament:cache-reset
     

Debugging Tips

• Inspect Rendered Icons: Use browser dev tools to verify the correct SVG is loaded (check data-icon attributes).
• Log Alias Mappings: Add a temporary debug method to PhosphorIcons service provider:

  public function boot() {
      \Log::info('Phosphor Alias Mappings:', [
          'heroicon-o-cog-6-tooth' => PhosphorIcons::getAliasMap()['heroicon-o-cog-6-tooth'] ?? 'Not mapped',
      ]);
  }
  

Extension Points

1. Custom Icon Sets: Extend the PhosphorIcons class to add domain-specific icons:

   class CustomPhosphorIcons extends PhosphorIcons {
       public static function make(): static {
           static::registerIcon('custom-icon', 'path/to/svg.svg');
           return parent::make();
       }
   }
   

2. Dynamic SVG Injection: Override the SVG rendering logic in app/Providers/AppServiceProvider:

   public function boot() {
       Icon::macro('customSvg', function ($icon, $attributes = []) {
           return '<svg>'.file_get_contents(resource_path("views/svg/{$icon}.svg")).'</svg>';
       });
   }
   

3. Style Presets: Create a config file for reusable style presets:

   // config/phosphor-presets.php
   return [
       'dashboard' => PhosphorIcons::STYLE_LIGHT,
       'admin' => PhosphorIcons::STYLE_BOLD,
   ];
   

   Then load them in your PanelProvider:

   PhosphorIcons::make()->style(config('phosphor-presets.dashboard'));
   

Performance Tips

• Lazy-Load Styles: Use JavaScript to dynamically apply styles if icons are heavy:

  document.addEventListener('DOMContentLoaded', () => {
      if (window.location.pathname.includes('admin')) {
          document.querySelectorAll('[data-icon]').forEach(el => {
              el.style.setProperty('--icon-style', 'bold');
          });
      }
  });
  

• SVG Optimization: Minify Phosphor SVGs via SVGO and republish the package locally.

Testing

• Unit Test Icon Renders:

  public function test_icon_renders_correctly() {
      $icon = Icon::make(Phosphor::Cog)->size(24);
      $this->assertStringContainsString('cog', $icon->getSvg());
  }
  

• Style Isolation Tests:

  public function test_style_override() {
      PhosphorIcons::make()->overrideStyleForAlias('heroicon-o-cog-6-tooth', PhosphorIcons::STYLE_BOLD);
      $icon = Icon::make('heroicon-o-cog-6-tooth');
      $this->assertStringContainsString('bold', $icon->getSvg());
  }