Getting Started

Minimal Setup for Laravel

Install the package (via Composer):
```
composer require symfony/ux-icons
```

Register Twig (if not already set up):

For Laravel 9+ with Twig integration:
```
composer require symfony/twig-bundle
```

Add to config/app.php:

'providers' => [
    // ...
    Symfony\Bundle\TwigBundle\TwigBundle::class,
],

Configure Twig (in config/twig.php):

return [
    'paths' => [
        // ...
        __DIR__.'/../resources/views/icons' => 'icons',
    ],
];

First Icon Usage (in a Twig template):
```
{{ ux_icon('mdi:check', {class: 'w-4 h-4'}) }}
```
- Place SVGs in resources/views/icons/mdi/check.svg.twig (or use remote icons via Iconify).

First Use Case: Dynamic Admin Dashboard Icons

{# resources/views/admin/dashboard.twig #}
{% for user in users %}
    <div class="flex items-center">
        {{ ux_icon(
            user.role === 'admin' ? 'mdi:shield' : 'mdi:account',
            {class: 'w-5 h-5 mr-2'}
        ) }}
        <span>{{ user.name }}</span>
    </div>
{% endfor %}

Implementation Patterns

1. Local SVG Workflow

Directory Structure:

resources/
└── views/
    └── icons/
        ├── mdi/
        │   ├── check.svg.twig
        │   └── home.svg.twig
        └── custom/
            └── logo.svg.twig

Template Example (resources/views/icons/mdi/check.svg.twig):

<svg viewBox="0 0 24 24" fill="currentColor" {% for attr, value in attributes %}{{ attr }}="{{ value }}"{% endfor %}>
    <path d="M9 16.17L4.59 12 8.19 8.41 10 10.29 14.59 5.71 16.41 7.59 10 14z"/>
</svg>

Usage:

{{ ux_icon('mdi:check', {class: 'text-green-500'}) }}

2. Remote SVG Integration (Iconify)

Configuration (config/packages/ux_icons.yaml):

ux_icons:
    icon_sets:
        mdi: https://cdn.jsdelivr.net/npm/@mdi/js@7.2.97/svg/iconify.json
    ignore_not_found: true

Usage:
```
{{ ux_icon('mdi:home', {class: 'w-6 h-6'}) }}
```
- Automatically fetches and caches SVGs from Iconify.

3. Twig Component Pattern

Reusable Icon Component (resources/views/components/icon.twig):

<twig:ux:icon
    name="{{ name }}"
    class="{{ class ?? 'w-4 h-4' }}"
    aria-label="{{ aria_label ?? '' }}"
/>

Usage in Blade:

@twig('components/icon.twig', ['name' => 'mdi:check', 'class' => 'text-red-500'])

4. Dynamic Icon Generation

Helper Class (app/Helpers/IconHelper.php):

namespace App\Helpers;

use Symfony\UX\Icons\IconRenderer;

class IconHelper {
    public static function render(string $name, array $options = []): string {
        $renderer = new IconRenderer();
        return $renderer->render($name, $options);
    }
}

Usage in Blade:

{!! \App\Helpers\IconHelper::render('mdi:home', ['class' => 'w-5 h-5']) !!}

5. Icon Sets and Aliases

Configuration (config/ux_icons.yaml):

ux_icons:
    icon_sets:
        custom: /path/to/local/icons
    aliases:
        home: mdi:home
        user: mdi:account

Usage:

{{ ux_icon('home', {class: 'w-5 h-5'}) }} {# Renders mdi:home #}

6. Caching Remote SVGs

Custom Cache Strategy (Service Provider):

// app/Providers/IconServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Symfony\UX\Icons\IconRenderer;
use Illuminate\Support\Facades\Cache;

class IconServiceProvider extends ServiceProvider {
    public function boot() {
        $renderer = new IconRenderer();
        $renderer->setIconLoader(function ($name) {
            return Cache::remember(
                "icon_{$name}",
                now()->addHours(1),
                function () use ($name) {
                    // Custom logic to fetch remote/local SVGs
                    return file_get_contents("https://cdn.example.com/icons/{$name}.svg");
                }
            );
        });
    }
}

7. Integration with Tailwind CSS

Dynamic Sizing:

{{ ux_icon('mdi:check', {class: 'w-6 h-6 text-blue-500'}) }}

Themeable Icons:

{{ ux_icon('mdi:heart', {
    class: 'w-5 h-5',
    'fill': 'currentColor',
    'stroke-width': '1.5'
}) }}

8. Livewire/Alpine Integration

Livewire Component:

// app/Http/Livewire/Admin/UserIcon.php
namespace App\Http\Livewire;

use Livewire\Component;
use App\Helpers\IconHelper;

class UserIcon extends Component {
    public $userRole;

    public function render() {
        return view('livewire.admin.user-icon', [
            'icon' => IconHelper::render(
                $this->userRole === 'admin' ? 'mdi:shield' : 'mdi:account',
                ['class' => 'w-5 h-5']
            ),
        ]);
    }
}

Template:

<div>
    {!! $icon !!}
    <span>{{ $user->name }}</span>
</div>

Gotchas and Tips

Pitfalls

Twig vs. Blade Conflicts:
- Issue: Twig functions (e.g., ux_icon) won’t work in Blade templates by default.
- Fix: Use @twig directives or create a Blade wrapper:
```
@php
    $iconRenderer = new \Symfony\UX\Icons\IconRenderer();
    echo $iconRenderer->render('mdi:check', ['class' => 'w-4 h-4']);
@endphp
```
Remote SVG Caching Headaches:
- Issue: Remote SVGs may not cache properly, causing flickering.
- Fix: Implement a versioned cache key or use Laravel’s Cache::forever() for static icons.
XMLNS Attribute Breaking Tests:
- Issue: Upgrading to UX Icons 2.24+ adds xmlns to SVGs, breaking string-based assertions in tests.
- Fix: Lock icons on demand before testing:
```
$renderer = new IconRenderer();
$renderer->lockOnDemand(true); // Force-lock all icons
```
Icon Not Found Errors:
- Issue: ux_icon() throws exceptions for missing icons.
- Fix: Enable ignore_not_found in config:
```
ux_icons:
    ignore_not_found: true
```

SVG Security Risks:

Issue: Remote SVGs can expose XXE vulnerabilities if not sanitized.

Fix: Whitelist domains and validate SVGs:

$renderer->setIconLoader(function ($name) {
    $url = "https://trusted-cdn.com/icons/{$name}.svg";
    $svg = @file_get_contents($url);
    if (!$svg || strpos($svg, '<!DOCTYPE') !== false) {
        throw new \RuntimeException("Invalid SVG: {$name}");
    }
    return $svg;
});

Twig Component Caching:
- Issue: <twig:ux:icon> may not respect Laravel’s cache tags.
- Fix: Use manual caching in Blade:

Ux Icons Laravel Package