Php Feather Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require pixelrobin/php-feather:^2.0
   

   Add the service provider to config/app.php:

   'providers' => [
       PixelRobin\Feather\FeatherServiceProvider::class,
   ],
   

2. Basic Usage Render an icon directly in a Blade view:

   @feather('home')
   

   This outputs the SVG for the home icon from Feather Icons (now updated to v4.x).

3. First Use Case Fetch and render an icon dynamically:

   use PixelRobin\Feather\Facades\Feather;
   $icon = Feather::icon('users');
   echo $icon->render();
   

Implementation Patterns

Core Workflows

1. Dynamic Icon Rendering Use the facade or service container with the modern API:

   // Facade (preferred)
   Feather::icon('search')->render();
   
   // Service Container
   app('feather')->icon('settings')->render();
   

2. Blade Directives Enhanced Blade support with auto-escaping for security:

   @feather('edit', ['class' => 'text-blue-500', 'aria-label' => 'Edit'])
   

   Supports all SVG attributes (class, width, height, fill, aria-*, etc.).

3. Customizing Icons Extend with aliases or custom logic:

   // Add an alias for an existing icon
   Feather::alias('edit-alt', 'edit');
   
   // Extend with custom attributes
   Feather::macro('withTooltip', function ($tooltip) {
       return $this->withAttribute('aria-label', $tooltip);
   });
   

4. PHP Preload Support Register the package for PHP preloading (if enabled):

   // In composer.json
   "autoload": {
       "psr-4": {
           "PixelRobin\\Feather\\": "vendor/pixelrobin/php-feather/src"
       },
       "preload": true,
       "preload-autoload": true
   }
   

Advanced Patterns

• Icon Collections Group icons with improved syntax:

  Feather::collection('admin', ['dashboard', 'users', 'settings']);
  

  Render all in a loop:

  @foreach(Feather::collection('admin') as $icon)
      @feather($icon->name)
  @endforeach
  

• Accessibility Leverage built-in ARIA support:

  @feather('user', ['aria-label' => 'Profile', 'aria-hidden' => 'false'])
  

• API Responses Return SVG icons in API responses with proper escaping:

  return response()->json([
      'icon' => Feather::icon('download')->toHtml()
  ]);
  

• Conditional Icons Use Laravel’s Blade conditionals with dynamic icons:

  @if(auth()->check())
      @feather('user', ['aria-label' => 'User Profile'])
  @else
      @feather('log-in', ['aria-label' => 'Login'])
  @endif
  

Gotchas and Tips

Pitfalls

1. Breaking Changes in v2.0

   • PHP Version: Minimum PHP version is now 8.0 (removed 7.3 support).
   • Icon Storage: Icons are now stored as objects with static properties. Direct access to SVG strings is deprecated; use $icon->render() or $icon->toHtml().
   • Attribute Handling: Attributes are now escaped by default to prevent XSS. Use withAttribute() for dynamic values:

     Feather::icon('home')->withAttribute('class', 'safe-class');
     

2. Icon Availability

   • The package now automatically updates with new Feather Icons (v4.x). Check Feather Icons for the latest list.
   • Use Feather::availableIcons() to list supported icons.

3. Deprecated Methods

   • Avoid $icon->svg (use $icon->render() instead).
   • Avoid direct Blade directives like @feather('icon', ['unsafe' => 'html']) unless necessary.

4. Preload Compatibility Ensure your composer.json is configured for preloading if using PHP 8.0+:

   "autoload": {
       "preload": true,
       "preload-autoload": true
   }
   

Debugging Tips

• Missing Icons or Aliases Verify the icon name or alias exists:

  dd(Feather::availableIcons()); // List all icons
  dd(Feather::aliases());        // List all aliases
  

• Attribute Issues Debug dynamic attributes with:

  dd(Feather::icon('home')->getAttributes());
  

• Blade Directive Errors Ensure the directive is registered in AppServiceProvider (v2.0 uses a more robust registration):

  // No manual registration needed in v2.0; handled by the service provider.
  

• XSS Warnings If using dynamic attributes, escape values explicitly:

  $safeValue = htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
  Feather::icon('home')->withAttribute('title', $safeValue);
  

Extension Points

1. Custom Icon Sets Override the default icon resolver:

   Feather::resolver(function ($iconName) {
       return new CustomIconResolver($iconName);
   });
   

2. Automated Icon Updates The package now supports automated updates for new Feather Icons. To disable:

   config(['feather.auto_update' => false]);
   

3. Accessibility Enhancements Add custom ARIA roles or labels:

   Feather::macro('withRole', function ($role) {
       return $this->withAttribute('role', $role);
   });
   

4. Testing Mock the Feather facade in tests with the new object-oriented API:

   $mockIcon = Mockery::mock(PixelRobin\Feather\Icon::class);
   $mockIcon->shouldReceive('render')->andReturn('<svg>...</svg>');
   
   $this->mock(Feather::class)
        ->shouldReceive('icon')
        ->with('home')
        ->andReturn($mockIcon);
   

5. Performance Cache rendered icons for frequent use:

   $cachedIcon = Cache::remember("feather_{$iconName}", now()->addHours(1), function () use ($iconName) {
       return Feather::icon($iconName)->render();
   });
   

6. Localization Support multiple icon sets (e.g., solid/outline) via config:

   config(['feather.default_set' => 'outline']);
   Feather::set('solid'); // Switch sets dynamically