Blade Fontawesome Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require owenvoke/blade-fontawesome
   

2. Publish the config (optional, for customization):

   php artisan vendor:publish --tag=blade-fontawesome-config
   

3. Use an icon in Blade:

   <x-fas-cloud class="text-blue-500"/>
   

First Use Case: Replacing Legacy Icons

Replace outdated <i class="fas fa-user"></i> with:

<x-fas-user class="text-gray-600"/>

Why? Eliminates manual class management and leverages Blade’s component syntax for better IDE support.

Implementation Patterns

Core Workflows

1. Icon Component Usage

• Basic:

  <x-fas-home/>
  

• With Classes/Styles:

  <x-fas-home class="w-8 h-8 text-green-500 hover:text-green-700"/>
  

• Dynamic Icons (via Blade directives):

  @icon('fas-' . $iconName, ['class' => 'text-blue-500'])
  

2. Icon Set Management

• Disable Pro Sets (e.g., Sharp icons):

  // config/blade-fontawesome.php
  'sharp-solid' => false,
  

• Use Raw SVGs (published assets):

  <img src="{{ asset('vendor/blade-fontawesome/solid/cloud.svg') }}" alt="Cloud"/>
  

3. Font Awesome Pro/Kits

• Sync Pro Icons:

  php artisan blade-fontawesome:sync-icons --pro
  

• Sync Custom Kit:

  php artisan blade-fontawesome:sync-icons --kit=YOUR_KIT_CODE
  

4. Caching for Performance

• Cache pro/kit icons to reduce runtime overhead:

  php artisan icons:cache
  

Integration Tips

With Livewire/Alpine.js

Use icons in dynamic components:

<button x-on:click="$wire.save()">
    <x-fas-save class="mr-2"/>
    Save
</button>

With Tailwind CSS

Combine with Tailwind classes for responsive icons:

<x-fas-search class="w-5 h-5 md:w-6 md:h-6 text-gray-400"/>

Custom Icon Components

Extend the package to create domain-specific icons:

<!-- resources/views/components/icons/alert.blade.php -->
<x-fas-exclamation-triangle class="{{ $class ?? 'text-yellow-500' }}"/>

Usage:

<x-icons.alert class="text-red-500"/>

Service Provider Integration

Register global icon helpers in AppServiceProvider:

use Owenvoke\BladeFontAwesome\Facades\BladeFontAwesome;

public function boot()
{
    BladeFontAwesome::addDefaultClass('text-gray-600');
}

Gotchas and Tips

Pitfalls

1. Icon Set Conflicts:

   • Issue: Using fas and sharp-solid simultaneously may cause duplicate icon definitions.
   • Fix: Disable unused sets in config/blade-fontawesome.php:

     'sharp-solid' => env('APP_ENV') !== 'production',
     

2. Pro/Kit Icons Not Loading:

   • Issue: Icons from --pro or --kit sync don’t appear.
   • Debug:
     • Verify resources/icons/blade-fontawesome exists.
     • Check storage/framework/cache/data for cached icons (clear with php artisan cache:clear).
     • Ensure npm installed the correct kit (npm list @awesome.me/kit-*).

3. Blade Caching Issues:

   • Issue: Changes to icon components aren’t reflected.
   • Fix: Clear Blade cache:

     php artisan view:clear
     

4. PHP 8.3+ Compatibility:

   • Issue: CompileSvgsAction errors in newer PHP versions.
   • Fix: Update to v3.2.1+ or patch the service provider (see PR #107).

Debugging Tips

1. List Available Icons:

   php artisan blade-fontawesome:list
   

   Outputs all registered icons (useful for troubleshooting missing icons).

2. Check Published Assets:

   • Verify SVGs are published to public/vendor/blade-fontawesome/:

     php artisan vendor:publish --tag=blade-fontawesome --force
     

3. Log Icon Renders: Add a temporary debug directive in AppServiceProvider:

   Blade::directive('icondebug', function ($expression) {
       \Log::debug("Rendering icon: $expression");
       return "<?php echo '<!-- DEBUG: $expression -->'; ?>";
   });
   

   Usage:

   @icondebug('fas-home')
   

Extension Points

1. Custom Icon Directives: Extend Blade directives for domain-specific icons:

   // app/Providers/BladeServiceProvider.php
   Blade::directive('usericon', function ($icon) {
       return "<x-fas-user class=\"{$icon}\"/>";
   });
   

   Usage:

   @usericon('text-blue-500')
   

2. Dynamic Icon Loading: Lazy-load icons based on user roles:

   @if(auth()->user()->isAdmin())
       <x-fas-user-shield/>
   @else
       <x-fas-user/>
   @endif
   

3. Icon Variants: Create wrapper components for themed icons:

   <!-- resources/views/components/icons/primary.blade.php -->
   <x-fas-{{ $icon }} class="text-primary-500"/>
   

   Usage:

   <x-icons.primary icon="home"/>
   

4. Accessibility Enhancements: Add ARIA labels dynamically:

   // app/Providers/BladeServiceProvider.php
   Blade::component('fas-home', function ($component, $slot) {
       $component->withAttributes(['aria-label' => 'Home']);
       return $component;
   });
   

Configuration Quirks

1. Default Classes/Attributes: Set global defaults in config/blade-fontawesome.php:

   'default_classes' => 'text-gray-600',
   'default_attributes' => ['role' => 'img'],
   

2. Self-Hosting Font Awesome: Disable CDN and use local assets:

   'cdn' => false,
   'local_path' => 'fonts/fontawesome',
   

   Then publish assets:

   php artisan vendor:publish --tag=blade-fontawesome --force
   

3. Icon Naming Conflicts: Rename conflicting icons in config/blade-fontawesome.php:

   'aliases' => [
       'fas-home-alt' => 'fas-home',
   ],
   

Performance Optimizations

1. Cache Pro/Kit Icons:

   php artisan icons:cache
   

   Reduces runtime icon resolution overhead.

2. Tree-Shake Unused Icons: If using Webpack/Vite, manually import only needed icons to reduce bundle size:

   import { faUser, faHome } from '@fortawesome/free-solid-svg-icons';
   

3. Inline Critical Icons: For above-the-fold content, inline SVG directly in Blade:

   {!! file_get_contents(public_path('vendor/blade-fontawesome/solid/home.svg')) !!}