Filament Phosphor Icons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tonegabes/filament-phosphor-icons
   

   Publish assets if needed (though this package is icon-only, no assets to publish).

2. First Use Case: Replace default Filament icons (e.g., heroicon-o-*) with Phosphor icons in a single line:

   use ToneGabes\Filament\Icons\Enums\Phosphor;
   
   Action::make('edit')
       ->icon(Phosphor::Pencil); // Replaces `heroicon-o-pencil`
   

3. Where to Look First:

   • Phosphor Icons Website for visual reference.
   • Filament Icon Docs for usage patterns.
   • The Phosphor enum autocompletion in your IDE (all 4,000+ icons are available).

Implementation Patterns

Core Workflows

1. Replacing Default Icons:

   // Before (Filament default)
   ->icon('heroicon-o-check')
   
   // After (Phosphor)
   ->icon(Phosphor::Check)
   

2. Dynamic Icon Selection: Use enums in conditional logic (e.g., toggle states, status badges):

   $icon = $record->is_active ? Phosphor::CheckCircle : Phosphor::XCircle;
   Badge::make()->icon($icon);
   

3. Consistent Styling: Pair with Weight enum for visual hierarchy:

   Button::make()
       ->icon(Phosphor::GearBold)
       ->iconWeight(Weight::Bold); // Forces bold style
   

4. Bulk Replacement: Create a helper trait to standardize icon usage:

   trait UsesPhosphorIcons {
       protected function phosphor(string $name): string {
           return Phosphor::from($name)->value;
       }
   }
   

5. Custom Icon Sets: Extend the enum for project-specific icons:

   enum CustomPhosphor extends Phosphor {
       case ProjectLogo = 'your-custom-icon';
   }
   

Integration Tips

• Filament 4/5 Compatibility: Works identically in both versions.
• Theming: Phosphor icons support CSS variables (e.g., --filament-icon-color).
• Performance: Zero runtime overhead—icons are statically resolved.

Gotchas and Tips

Pitfalls

1. Case Sensitivity: Phosphor icons are case-sensitive in the enum (e.g., Phosphor::Star ≠ Phosphor::star). Fix: Use IDE autocompletion or check the Phosphor API.

2. Missing Icons: Not all Phosphor icons are included by default. Verify availability via:

   dd(Phosphor::cases()); // List all loaded icons
   

   Fix: Ensure the package is up-to-date (composer update).

3. Weight Overrides: Forcing weights (e.g., Weight::Fill) may clash with Filament’s default styling. Fix: Inspect rendered HTML/CSS to adjust --filament-icon-weight variables.

4. Caching: Laravel’s opcache may cache enum values. Clear cache if icons appear broken:

   php artisan optimize:clear
   

Debugging

• Icon Not Rendering? Check the browser’s Network tab for failed icon requests (unlikely, but verify the package’s CDN/asset path).

• IDE Autocomplete Fails: Trigger PHPStan or Psalm to generate enum stubs:

  vendor/bin/phpstan analyse --generate-mock-files
  

Extension Points

1. Custom Icon Sets: Override the enum in config/filament-phosphor-icons.php:

   'custom_icons' => [
       'ProjectLogo' => 'your-icon-name',
   ],
   

2. Dynamic Icon Resolution: Create a macro for runtime icon resolution:

   Phosphor::macro('resolve', function (string $name) {
       return Phosphor::tryFrom($name) ?? Phosphor::Question;
   });
   

3. Filament Plugin Integration: Bundle with a custom Filament plugin for team-wide adoption:

   Filament::registerPlugin(
       Plugin::make()
           ->id('phosphor-icons')
           ->registerIcons(Phosphor::class)
   );
   

Pro Tips

• Icon Naming Conventions: Use *Fill for "active" states (e.g., Phosphor::CheckCircleFill). Use *Thin for subtle UI elements (e.g., Phosphor::ChevronDownThin).

• Accessibility: Pair icons with aria-label for screen readers:

  Button::make()
      ->icon(Phosphor::Bell)
      ->ariaLabel('Notifications');
  

• Dark Mode: Phosphor icons automatically adapt to dark mode via CSS variables. No extra config needed.