Getting Started

Minimal Setup

Install the package:

composer require blade-ui-kit/blade-icons

Publish the config and uncomment the default icon set (e.g., heroicons):
```
php artisan vendor:publish --tag=blade-icons
```
Place SVG files in the configured directory (default: resources/svg). For example:
```
resources/svg/heroicons/solid/camera.svg
```

Use an icon in Blade:

<x-icon-camera class="w-6 h-6" />

Or via the @svg directive:

@svg('heroicons.solid.camera', 'w-6 h-6')

First Use Case: Replacing Raw SVG

Replace this:

<svg fill="none" viewBox="0 0 24 24" stroke="currentColor" class="w-6 h-6">
  <!-- SVG path data -->
</svg>

With this:

<x-icon-camera class="w-6 h-6" />

Implementation Patterns

1. Icon Set Management

Default Icon Set: Configure in config/blade-icons.php:
```
'default' => 'heroicons',
```
Dynamic Icon Sets: Override the default per view or component:
```
@iconSet('feather')
<x-icon-user class="w-6 h-6" />
```

2. Component-Based Usage

PascalCase Components: Auto-generated for each SVG file (e.g., camera.svg → <x-icon-camera />).
Custom Naming: Rename components in app/Providers/BladeIconsServiceProvider.php:
```
BladeIcons::register('camera', 'custom-camera');
```

3. Directives for Flexibility

Basic Usage:

@svg('heroicons.solid.camera', ['class' => 'w-6 h-6'])

With Attributes:

@svg('heroicons.solid.camera', ['class' => 'w-6 h-6', 'aria-label' => 'Camera'])

Inline SVG: Access raw SVG content:

{!! svg('heroicons.solid.camera', ['class' => 'w-6 h-6']) !!}

4. Integration with Blade Components

Create a Reusable Icon Component:

@component('components.icon', ['name' => 'heroicons.solid.camera', 'classes' => 'w-6 h-6'])
@endcomponent

Dynamic Icons via Props:

<x-icon name="heroicons.solid.camera" class="w-6 h-6" />

5. Theming and Styling

CSS Classes: Leverage Tailwind or custom CSS:

<x-icon-camera class="text-blue-500 dark:text-blue-400" />

Inline Styles: Use the @svg directive:

@svg('heroicons.solid.camera', ['style' => 'color: red;'])

6. Lazy Loading Icons

Dynamic Icon Loading: Load icons only when needed (e.g., in Alpine.js):

<div x-data="{ showIcon: false }">
  <button @click="showIcon = true">Load Icon</button>
  <x-icon-camera x-show="showIcon" class="w-6 h-6" />
</div>

7. Icon Sets in a Multi-Tenant App

Per-Tenant Icon Sets: Override the config dynamically:

// In a middleware or service provider
config(['blade-icons.default' => Auth::user()->preferred_icon_set]);

Gotchas and Tips

Pitfalls

Missing SVG Files:
- Error: Class 'App\View\Components\IconCamera' not found.
- Fix: Ensure the SVG file exists in the configured path (e.g., resources/svg/heroicons/solid/camera.svg).
- Debug: Run php artisan blade-icons:list to verify registered icons.
Caching Issues:
- Error: Icons not updating after adding new SVGs.
- Fix: Clear Blade cache:
```
php artisan view:clear
```
- Tip: Use php artisan blade-icons:clear-cache (if available in newer versions).
Namespace Conflicts:
- Error: Class 'IconCamera' conflicts with another component.
- Fix: Rename components in the service provider or use fully qualified names:
```
<x-icons::heroicons::solid::camera />
```
SVG ViewBox or Fill Attributes:
- Issue: Icons not rendering correctly due to missing viewBox or fill attributes.
- Fix: Ensure SVGs are properly formatted. Use the @svg directive to override attributes:
```
@svg('heroicons.solid.camera', ['fill' => 'currentColor', 'viewBox' => '0 0 24 24'])
```
Case Sensitivity:
- Issue: Icons not found due to case mismatches (e.g., Camera vs. camera).
- Fix: Stick to lowercase filenames (e.g., camera.svg) and use kebab-case in Blade:
```
<x-icon-camera />  
```

Debugging Tips

List Registered Icons:
```
php artisan blade-icons:list
```
Outputs all available icons and their paths.
Inspect SVG Content: Use the @svg directive to dump raw SVG content:
```
@dump(svg('heroicons.solid.camera'))
```
Check Config: Verify the config/blade-icons.php file for correct paths and icon sets.

Extension Points

Custom Icon Sets:

Add a New Set: Publish the config and add your set:

'sets' => [
    'heroicons' => resource_path('svg/heroicons'),
    'custom' => resource_path('svg/custom-icons'),
],

Register Dynamically:

BladeIcons::add('custom', resource_path('svg/custom-icons'));

Modify SVG Output:

Override Attributes: Use the @svg directive with custom attributes:

@svg('heroicons.solid.camera', [
    'class' => 'w-6 h-6',
    'xmlns' => 'http://www.w3.org/2000/svg',
    'role' => 'img',
])

Post-Process SVGs: Extend the BladeIconsServiceProvider to modify SVG tags:

BladeIcons::macro('modifySvg', function ($svg, $name) {
    return str_replace('<svg', '<svg role="img"', $svg);
});

Icon Aliases:

Shorten Names: Create aliases in the service provider:

BladeIcons::alias('user', 'heroicons.solid.user');

Now use:

<x-icon-user />  <!-- Instead of <x-icon-heroicons-solid-user /> -->

Icon Sets from External Sources:

Remote SVGs: Fetch and cache SVGs dynamically (advanced use case):

BladeIcons::addRemote('remote-icons', 'https://example.com/icons/', function ($name) {
    return file_get_contents("https://example.com/icons/{$name}.svg");
});

Performance Tips

Cache Icons: Use Laravel’s cache to store SVG content:
```
BladeIcons::cacheSvg(true);
```

Lazy Load Icon Sets: Load only the icon sets you need:

BladeIcons::loadSet('heroicons');
BladeIcons::loadSet('feather');

Testing

Unit Test Icons:

public function test_icon_rendering()
{
    $this->blade->render('<x-icon-camera />')
        ->assertSee('<svg');
}

Verify SVG Content:

public function test_svg_content()
{
    $svg = svg('heroicons.solid.camera');
    $this->assertStringContainsString('viewBox="0 0 24 24"', $svg);
}

Advanced: Custom Directives

Extend the @svg directive in the service provider:

Blade::directive('icon', function ($expression) {
    return "<?php echo blade_icons_svg({$expression}); ?>";
});