Blade Icons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require orchid/blade-icons
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Orchid\BladeIcons\BladeIconsServiceProvider" --tag="config"
   

2. Basic Usage: Register an icon set (e.g., feather) in config/blade-icons.php:

   'sets' => [
       'feather' => [
           'path' => 'vendor/orchid/blade-icons/src/sets/feather',
       ],
   ],
   

3. First Use Case: Render an icon in a Blade template:

   <x-blade-icons.icon name="home" set="feather" />
   

   Or use the helper:

   {{ blade_icon('home', 'feather') }}
   

Implementation Patterns

Common Workflows

1. Dynamic Icon Rendering: Use Blade components or helpers to render icons dynamically based on conditions:

   @if($user->isAdmin)
       <x-blade-icons.icon name="users" set="feather" />
   @else
       <x-blade-icons.icon name="user" set="feather" />
   @endif
   

2. Custom Icon Sets: Add your own icon sets by extending the Orchid\BladeIcons\Sets\Set class and registering them in the config:

   'custom' => [
       'path' => 'app/BladeIcons/Sets/Custom',
   ],
   

3. Integration with Orchid Platform: If using Orchid Platform, leverage the built-in icon support:

   <span class="icon">
       <x-blade-icons.icon name="settings" set="feather" />
   </span>
   

4. SVG Customization: Pass additional attributes to modify SVG output:

   <x-blade-icons.icon name="edit" set="feather" class="text-red-500" width="24" />
   

5. Caching Icons: Pre-render icons in a view composer or service provider for performance:

   BladeIcons::render('home', 'feather'); // Cache the rendered SVG
   

Gotchas and Tips

Pitfalls

1. Icon Set Paths: Ensure paths in config/blade-icons.php are correct. Use relative paths (e.g., vendor/orchid/blade-icons/src/sets/feather) for packaged sets and absolute paths (e.g., app/BladeIcons/Sets/Custom) for custom sets.

2. Namespace Conflicts: Avoid naming custom icon sets or files to conflict with existing sets (e.g., don’t name a custom set feather).

3. SVG Security: Sanitize dynamic icon names to prevent SVG injection attacks:

   $safeName = htmlspecialchars($request->input('icon_name'));
   

4. Caching Issues: Clear Blade cache if icons fail to render after updates:

   php artisan view:clear
   

Debugging Tips

1. Check Registered Sets: Dump registered sets to verify configuration:

   dd(config('blade-icons.sets'));
   

2. Verify Icon Existence: Ensure the icon file exists in the specified set directory (e.g., vendor/orchid/blade-icons/src/sets/feather/home.svg).

3. Debug SVG Output: Use {{ blade_icon('home', 'feather', true) }} to output raw SVG for inspection.

Extension Points

1. Custom SVG Processing: Extend the Orchid\BladeIcons\BladeIcons facade to modify SVG output:

   BladeIcons::extend(function ($svg) {
       return str_replace('<svg', '<svg data-custom="attribute"', $svg);
   });
   

2. Icon Aliases: Create aliases for frequently used icons in a service provider:

   BladeIcons::alias('home', 'feather/home');
   // Usage:
   <x-blade-icons.icon name="home" />
   

3. Dynamic Set Loading: Load icon sets dynamically based on user roles or environments:

   if (app()->environment('production')) {
       config(['blade-icons.sets.production' => [...]]);
   }