Blade Pixelicon Icons Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require daljo25/blade-pixelicon-icons
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Daljo25\BladePixeliconIcons\BladePixeliconIconsServiceProvider"
   

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

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

   Example output:

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

3. Where to Look First

   • Config File: config/blade-pixelicon-icons.php (default paths, icon sets).
   • Blade Directives: Check app/Providers/BladePixeliconIconsServiceProvider.php for registered directives.
   • Icon List: Browse the Pixel Icons Library for available icons.

Implementation Patterns

Common Workflows

1. Basic Icon Usage

   @pixelicon('user', ['class' => 'text-gray-600'])
   

   • Automatically resolves to the correct SVG path from the library.

2. Dynamic Icons with Variables

   @pixelicon($dynamicIconName, ['class' => 'w-5 h-5'])
   

   • Useful for conditional rendering (e.g., {{ $user->role === 'admin' ? 'admin' : 'user' }}).

3. Customizing Icons

   • Inline SVG Attributes:

     @pixelicon('settings', ['class' => 'fill-current', 'width' => '24', 'height' => '24'])
     

   • Wrapper Classes:

     <div class="p-2">
       @pixelicon('search', ['class' => 'text-gray-400'])
     </div>
     

4. Integration with Tailwind CSS

   @pixelicon('bell', ['class' => 'w-6 h-6 text-indigo-500 hover:text-indigo-700'])
   

   • Leverage Tailwind’s utility classes for responsive sizing and theming.

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

   @component('components.icon', ['name' => 'edit', 'classes' => 'text-green-500'])
   @endcomponent
   

   <!-- resources/views/components/icon.blade.php -->
   @pixelicon($name, ['class' => $classes])
   

6. Icon Sets If the package supports multiple icon sets (e.g., solid, outline), specify the set:

   @pixelicon('set:outline|home', ['class' => 'w-6 h-6'])
   

Gotchas and Tips

Pitfalls

1. Icon Not Found

   • Cause: The icon name doesn’t match the library’s naming convention (e.g., home vs. home-alt).
   • Fix: Verify the exact icon name in the Pixel Icons Library. Use lowercase and hyphens (e.g., user-profile).

2. Caching Issues

   • Cause: Blade directives may not update after changes if the view cache is enabled.
   • Fix: Clear the view cache:

     php artisan view:clear
     

3. SVG Rendering Quirks

   • Cause: Some icons may not render correctly due to missing viewBox or fill attributes.
   • Fix: Override attributes explicitly:

     @pixelicon('star', ['fill' => 'currentColor', 'viewBox' => '0 0 24 24'])
     

4. Path Configuration

   • Cause: Icons fail to load if the icon_path in the config is incorrect.
   • Fix: Ensure the config points to the correct directory where the Pixel Icons library is stored (e.g., public/icons/pixel-icons).

Debugging Tips

1. Inspect the Generated SVG Use browser dev tools to check if the SVG is rendered correctly. Look for:

   • Missing or malformed SVG tags.
   • Incorrect paths (e.g., xlink:href pointing to a 404).

2. Log Icon Resolution Temporarily add logging to the directive to debug icon resolution:

   // In BladePixeliconIconsServiceProvider.php
   Blade::directive('pixelicon', function ($expression) {
       $iconName = eval("return {$expression};");
       \Log::debug("Resolving icon: {$iconName}");
       // ... rest of the directive logic
   });
   

3. Fallback for Missing Icons Provide a fallback SVG or text if an icon fails to load:

   @pixelicon($iconName ?? 'unknown', [
       'class' => 'text-gray-400',
       'fallback' => '?'
   ])
   

   (Note: Implement this in the package’s directive logic if not supported out-of-the-box.)

Extension Points

1. Custom Icon Sets Extend the package to support additional icon sets by:

   • Adding a new directory to the config’s icon_paths.
   • Overriding the resolveIconPath method in the service provider.

2. Dynamic Styling Add a filter for dynamic styling (e.g., based on user preferences):

   @pixelicon('theme:dark|moon', ['class' => 'text-white'])
   

   (Requires custom logic in the directive.)

3. Animation Support Animate icons using CSS or JavaScript by wrapping them:

   <div class="animate-pulse">
     @pixelicon('loading', ['class' => 'w-5 h-5'])
   </div>
   

4. Localization Support localized icon names (e.g., home → inicio for Spanish) by:

   • Extending the directive to accept a language parameter.
   • Mapping icon names in a language-specific config file.

Performance Tips

1. Inline Critical Icons For above-the-fold icons, inline the SVG directly in the Blade view to avoid extra HTTP requests:

   {!! file_get_contents(public_path('icons/pixel-icons/home.svg')) !!}
   

   (Use sparingly to avoid bloating your templates.)

2. Sprite Sheets Combine all icons into a sprite sheet and use CSS background-image for better performance:

   .icon-home { background-image: url('/icons/pixel-icons-sprite.svg#home'); }
   

   (Requires preprocessing the icons into a sprite sheet.)

3. Lazy Loading Defer non-critical icons using loading="lazy" on a parent container:

   <div loading="lazy">
     @pixelicon('non-critical-icon')
   </div>