Laravel Essential Icon Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require yeejiawei/laravel-essential-icon
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="YeeJiaWei\EssentialIcon\EssentialIconServiceProvider"
   

2. Register the Blade directive: Add the following to app/Providers/BladeServiceProvider.php (or create it if missing):

   public function boot()
   {
       $this->directive('icon', function ($expression) {
           return "<?php echo YeeJiaWei\\EssentialIcon\\EssentialIcon::render($expression); ?>";
       });
   }
   

3. First Use Case: Use the directive in Blade templates:

   @icon('icon-name', ['class' => 'text-blue-500'])
   

   Or via a component (if configured):

   <x-icon::icon-name class="text-red-500" />
   

Where to Look First

• Config File: Check config/essential-icon.php for default paths and icon sets.
• Service Provider: Review YeeJiaWei\EssentialIcon\EssentialIconServiceProvider for registration logic.
• Icon Renderer: Inspect YeeJiaWei\EssentialIcon\EssentialIcon for rendering logic and supported parameters.

Implementation Patterns

Usage Patterns

1. Blade Directive:

   @icon('home', ['class' => 'w-6 h-6'])
   

   • Supports dynamic icon names (e.g., @icon($dynamicIconName)).
   • Pass attributes as an array or directly:

     @icon('settings', class: 'text-gray-500')
     

2. Component-Based Usage: If configured, use components like:

   <x-icon::home class="text-green-500" />
   

   • Components are generated dynamically based on the icon set.

3. Custom Icon Sets: Extend the default icon set by publishing and modifying the config:

   'icons' => [
       'custom' => resource_path('views/vendor/essential-icon/custom'),
   ],
   

4. Dynamic Icon Selection: Use logic to select icons dynamically:

   $iconName = auth()->user()->role === 'admin' ? 'admin' : 'user';
   @icon($iconName)
   

Workflows

1. Icon Discovery:

   • Scan the resources/views/vendor/essential-icon directory for available icons.
   • Use php artisan vendor:publish to add new icon sets.

2. Theming Icons: Override icon styles via Tailwind/CSS classes:

   @icon('bell', ['class' => 'text-yellow-500 hover:text-yellow-700'])
   

3. Reusable Icon Components: Create a Blade component for consistent icon usage:

   <!-- resources/views/components/Icon.blade.php -->
   <x-icon::{{ $name }} {{ $attributes }} />
   

   Usage:

   <x-icon name="search" class="w-5 h-5" />
   

Integration Tips

1. Laravel Mix/Webpack: Ensure icon SVG files are processed if using custom icon sets (e.g., optimize SVGs with laravel-mix-svg).

2. Livewire/Alpine: Combine with Livewire for dynamic icon updates:

   <div x-data="{ active: false }">
       <button @click="active = !active">
           @icon(active ? 'check' : 'x', ['class' => 'w-4 h-4'])
       </button>
   </div>
   

3. Form Requests: Use icons in form buttons or inputs:

   <button type="submit" class="flex items-center">
       @icon('paper-plane', ['class' => 'mr-2'])
       Submit
   </button>
   

Gotchas and Tips

Pitfalls

1. Missing Icons:

   • If an icon is not rendered, verify:
     • The icon file exists in the configured path (e.g., resources/views/vendor/essential-icon/fontawesome/home.svg).
     • The filename matches the directive argument (case-sensitive).
   • Debug with:

     dd(YeeJiaWei\EssentialIcon\EssentialIcon::getIconPath('home'));
     

2. Blade Directive Not Registered:

   • Ensure BladeServiceProvider is registered in config/app.php under providers.
   • Clear Blade cache if changes are not reflected:

     php artisan view:clear
     

3. Component Naming Conflicts:

   • If using components, avoid naming conflicts with existing Blade components.
   • Prefix custom components (e.g., <x-app-icon::home />).

4. SVG Optimization:

   • Large or unoptimized SVGs may impact performance. Use tools like svgo to optimize icon files.

Debugging

1. Check Icon Paths: Dump the resolved icon path to verify correctness:

   dd(config('essential-icon.icons.fontawesome') . '/home.svg');
   

2. View Source: Inspect the rendered HTML to confirm the SVG is loaded:

   <svg class="...">...</svg>
   

3. Log Errors: Add error handling to the directive:

   $this->directive('icon', function ($expression) {
       try {
           return "<?php echo YeeJiaWei\\EssentialIcon\\EssentialIcon::render($expression); ?>";
       } catch (\Exception $e) {
           return "<?php echo '<span class=\"text-red-500\">Icon Error</span>'; ?>";
       }
   });
   

Tips

1. Custom Icon Sets:

   • Add new icon sets by extending the config:

     'icons' => [
         'custom' => base_path('resources/views/vendor/essential-icon/custom'),
         'material' => base_path('resources/views/vendor/essential-icon/material-icons'),
     ],
     

   • Use a package like laravel-essential-icon-generator (if available) to auto-generate icon files.

2. Icon Size Consistency: Standardize icon sizes using Tailwind classes:

   @icon('user', ['class' => 'w-5 h-5'])
   

3. Dark Mode Support: Use CSS variables or Tailwind’s dark mode classes:

   @icon('moon', ['class' => 'dark:text-gray-300'])
   

4. Fallback Icons: Provide a fallback for missing icons:

   @icon($iconName ?? 'question', ['class' => 'w-4 h-4'])
   

5. Performance:

   • Cache icon paths if frequently accessed:

     static $iconPaths = [];
     if (!isset($iconPaths[$name])) {
         $iconPaths[$name] = EssentialIcon::getIconPath($name);
     }
     

   • Inline critical icons to reduce HTTP requests.

6. Testing: Test icon rendering in PHPUnit:

   public function test_icon_rendering()
   {
       $this->blade('@icon("home")')
            ->assertSee('<svg');
   }
   

7. Extension Points:

   • Extend the EssentialIcon class to add custom logic (e.g., icon modifiers):

     public static function render($name, $attributes = [])
     {
         $attributes['data-custom'] = 'value';
         return parent::render($name, $attributes);
     }