Blade Phosphor Icons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codeat3/blade-phosphor-icons
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Codeat3\BladePhosphorIcons\BladePhosphorIconsServiceProvider" --tag="config"
   

2. First Use Case: Add the directive to your Blade view:

   @phosphor("heroicons-outline:home")
   

   Or use the helper:

   {!! phosphorIcon('heroicons-outline:home') !!}
   

3. Where to Look First:

   • Package Documentation (if available)
   • config/blade-phosphor-icons.php (for customization)
   • resources/views/vendor/blade-phosphor-icons/ (default templates)

Implementation Patterns

Common Workflows

1. Dynamic Icons:

   @php
       $icon = request()->routeIs('dashboard') ? 'heroicons-outline:home' : 'heroicons-outline:dashboard';
   @endphp
   @phosphor($icon)
   

2. Reusable Components: Create a Blade component (resources/views/components/icon.blade.php):

   <x-icon :name="$name" :size="$size" :color="$color" />
   

   Usage:

   <x-icon name="heroicons-outline:user" size="24" color="blue-500" />
   

3. Integration with Tailwind CSS:

   @phosphor("heroicons-outline:bell", [
       'class' => 'text-blue-500 hover:text-blue-700',
       'aria-hidden' => 'true'
   ])
   

4. Conditional Rendering:

   @if(auth()->check())
       @phosphor("heroicons-outline:user-circle")
   @else
       @phosphor("heroicons-outline:user")
   @endif
   

5. Loop Through Icons:

   @foreach(['home', 'dashboard', 'settings'] as $route)
       @phosphor("heroicons-outline:{$route}")
   @endforeach
   

6. Laravel 13 Compatibility: The package now officially supports Laravel 13. Ensure your composer.json and dependencies are updated:

   "require": {
       "laravel/framework": "^13.0"
   }
   

Integration Tips

• Laravel Mix/Webpack: Use the package with your asset pipeline for optimized icon loading.
• Livewire/Alpine.js: Combine with dynamic components for interactive icons:

  <button x-on:click="toggle" @phosphor("heroicons-outline:toggle-left") />
  

• Form Buttons:

  <button type="submit" @phosphor("heroicons-outline:paper-airplane")>
      Submit
  </button>
  

Gotchas and Tips

Pitfalls

1. Icon Not Found:

   • Ensure the icon name matches Phosphor’s naming convention (e.g., heroicons-outline:home).
   • Verify the icon set is installed (e.g., heroicons-outline, heroicons-solid).
   • Check the config for custom icon paths:

     'icon_sets' => [
         'heroicons-outline' => resource_path('icons/heroicons-outline.svg'),
     ],
     

2. Caching Issues:

   • Clear Blade cache after updating icons:

     php artisan view:clear
     

   • If using Laravel Mix, rebuild assets:

     npm run dev
     

   • Production Caching: Icons are now optimized for caching in production. Ensure your cache is properly configured:

     php artisan config:cache
     php artisan route:cache
     

3. SVG Injection Risks:

   • Sanitize dynamic icon names to prevent SVG injection:

     $safeIcon = preg_replace('/[^a-zA-Z0-9:_-]/', '', $userInput);
     @phosphor($safeIcon)
     

Debugging

• Check Loaded Icons: Add this to a Blade view to debug available icons:

  @dump(\Codeat3\BladePhosphorIcons\Facades\PhosphorIcons::availableIcons())
  

• Inspect SVG Output: Use browser dev tools to verify the rendered SVG matches expectations.

Tips

1. Custom Icon Sets: Add your own SVG files to resources/icons/ and update the config:

   'icon_sets' => [
       'custom' => resource_path('icons/custom.svg'),
   ],
   

   Usage:

   @phosphor("custom:my-icon")
   

2. Size and Color: Pass attributes directly:

   @phosphor("heroicons-outline:star", [
       'width' => '20',
       'height' => '20',
       'fill' => 'currentColor',
       'style' => 'color: red'
   ])
   

3. Dark Mode Support: Use Tailwind’s dark mode classes with the icon:

   @phosphor("heroicons-outline:moon", [
       'class' => 'dark:text-yellow-300'
   ])
   

4. Performance:

   • Preload Critical Icons: Preload critical icons in your layout:

     @phosphor("heroicons-outline:home", ['class' => 'hidden'])
     

   • Inline Icons: Use the inline option to embed SVGs directly (avoids extra HTTP requests):

     @phosphor("heroicons-outline:home", ['inline' => true])
     

   • Production Caching: Leverage Laravel 13's improved caching mechanisms for better performance:

     php artisan optimize:clear
     

5. Testing: Test icon rendering in PHPUnit:

   $this->blade()->render('@phosphor("heroicons-outline:home")')
       ->assertSee('<svg');
   

6. Laravel 13 Migration:

   • If migrating from Laravel 12 to 13, ensure your AppServiceProvider is updated to use Laravel 13's boot method signature:

     public function boot(): void
     {
         // Your boot logic
     }
     

   • Verify your config/app.php includes the correct service provider registration.