Blade Icons

https://github.com/driesvints/blade-icons
Admin
A package to easily make use of SVG icons in your Laravel Blade views, allowing for simple...
Tokens:41,699
Snippets:328
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Factory instantiation example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Example of instantiating the Factory with a local filesystem, an IconsManifest, a filesystem manager, and a config array.

```php
use BladeUI\Icons\Factory;
use BladeUI\Icons\IconsManifest;
use Illuminate\Filesystem\Filesystem;

$factory = new Factory(
    new Filesystem,
    new IconsManifest(new Filesystem, base_path('bootstrap/cache/blade-icons.php')),
    $app->make(\Illuminate\Contracts\Filesystem\Factory::class),
    ['class' => 'icon icon-default'],
);
```

--------------------------------

### Example: registering components

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Example of adding a set and then calling `registerComponents()`. The comment shows the resulting Blade components: `<x-icon-camera>`, `<x-icon-solid.camera>`, etc.

```php
$factory->add('default', ['path' => 'resources/svg', 'prefix' => 'icon']);
$factory->registerComponents(); // registers <x-icon-camera>, <x-icon-solid.camera>, ...
```

--------------------------------

### write method usage example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Example of calling write with the factory's sets, which writes the manifest to bootstrap/cache/blade-icons.php.

```php
$manifest->write($factory->all());
// writes bootstrap/cache/blade-icons.php
```

--------------------------------

### Example: calling all()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Example of calling `all()` on a factory instance. The comment shows the expected return structure: an array keyed by set name with options including `prefix` and `paths`.

```php
$sets = $factory->all(); // ['default' => ['prefix' => 'icon', 'paths' => ['resources/svg'], ...]]
```

--------------------------------

### delete() usage example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Example call to delete the manifest file. Returns true when the file was removed.

```php
$deleted = $manifest->delete(); // true when the file was removed
```

--------------------------------

### Example: using contents()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example usage of the contents() method. Retrieves the raw SVG contents for the 'camera' icon.

```php
$icon = $factory->svg('camera');
$contents = $icon->contents(); // '<svg ...>...</svg>'
```

--------------------------------

### getManifest usage example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Example of calling getManifest with a factory's sets and the resulting manifest structure. Shows the expected return format with icon names.

```php
$sets = $factory->all(); // e.g. ['default' => ['paths' => ['resources/svg'], 'prefix' => 'icon']]
$manifest = $manifest->getManifest($sets);
// ['default' => ['resources/svg' => ['camera', 'foo-camera', 'solid.camera']]]
```

--------------------------------

### Example: using name()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example usage of the name() method. Creates an icon via the factory and echoes the icon name, which returns 'flag' for the 'zondicon-flag' icon.

```php
$factory = app(\BladeUI\Icons\Factory::class);
$icon = $factory->svg('zondicon-flag');
echo $icon->name(); // 'flag'
```

--------------------------------

### Creating an Svg instance

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example of creating an Svg instance with a name, raw SVG markup, and initial attributes.

```php
use BladeUI\Icons\Svg;

$svg = new Svg('camera', '<svg viewBox="0 0 24 24">...</svg>', ['class' => 'w-6 h-6']);
```

--------------------------------

### Adding icon sets with add()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Example of adding icon sets. The first uses 'path' and the second uses 'paths' which takes precedence.

```php
$factory->add('heroicons', [
    'path' => __DIR__.'/../resources/svg',
    'prefix' => 'heroicon',
    'class' => 'heroicon',
    'fallback' => 'o-x-circle',
    'attributes' => ['width' => 24],
]);

$factory->add('multi', [
    'paths' => ['resources/svg/a', 'resources/svg/b'], // wins over 'path'
    'prefix' => 'multi',
]);
```

--------------------------------

### Run icons:cache command

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Example of running the icons:cache command and its expected output.

```bash
php artisan icons:cache
# Blade icons manifest file generated successfully!
```

--------------------------------

### Run icons:clear command

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Example of running the icons:clear command and its expected output.

```bash
php artisan icons:clear
# Blade icons manifest file cleared!
```

--------------------------------

### Example config (config/blade-icons.php)

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/configuration.md

Complete example configuration for the blade-icons package. Defines a 'default' set with a path, optional disk, required prefix, fallback icon, default class, and optional attributes. Also includes global class, attributes, fallback, and component settings.

```php
<?php

return [

    'sets' => [
        'default' => [
            'path' => 'resources/svg',   // or 'paths' => ['resources/svg/a', 'resources/svg/b']
            // 'disk' => 's3-icons',     // relative to disk root when set
            'prefix' => 'icon',
            'fallback' => 'cake',
            'class' => 'icon-default',
            'attributes' => [
                // 'width' => 50,
                // 'height' => 50,
            ],
        ],
    ],

    'class' => '',

    'attributes' => [
        // 'width' => 50,
        // 'height' => 50,
    ],

    'fallback' => '',

    'components' => [
        'disabled' => false,
        'default' => 'icon',
    ],

];
```

--------------------------------

### write method error handling example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Example of using try-catch to handle exceptions thrown by write when the directory is not writable. Shows the error message format.

```php
use Exception;

try {
    $manifest->write($factory->all());
} catch (Exception $e) {
    // 'The /path/to/bootstrap/cache directory must be present and writable.'
}
```

--------------------------------

### Example: using svg()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Example of using `svg()` with classes, attributes, and a prefix. The first call passes a class string and attributes; the second passes attributes as the second argument; the third uses a prefix to target a specific set.

```php
$icon = $factory->svg('camera', 'w-6 h-6', ['data-foo' => 'bar']);
echo $icon->toHtml();
// '<svg class="w-6 h-6" data-foo="bar" ...>'

// Attributes as second argument (no classes):
$icon = $factory->svg('camera', ['style' => 'color: #fff']);

// Prefix targets a specific set:
$factory->svg('zondicon-flag');
```

--------------------------------

### toHtml() example with attributes

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example of calling toHtml() on an icon with attributes. The output shows the injected attributes in the SVG tag.

```php
$icon = $factory->svg('camera', 'w-6 h-6', ['data-baz' => true]);
echo $icon->toHtml();
// '<svg class="w-6 h-6" data-baz="1" ...>'
```

--------------------------------

### deferContent() example with custom hash

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example of creating a deferred icon with a custom hash and rendering it. The output shows the <use> reference and the Blade @once/@push block.

```php
use BladeUI\Icons\Svg;

$svg = new Svg('arrow', '<svg><path d="M14 5l7 7"/></svg>', ['defer' => 'my-hash']);
echo $svg->toHtml();
// '<svg><use href="#icon-my-hash"></use></svg>
//     @once("icon-my-hash") @push("bladeicons") <g id="icon-my-hash">...</g> @endpush @endonce'
```

--------------------------------

### Icon component usage example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Components.md

Example usage of the Icon component. The name attribute is mandatory; omitting it throws an ArgumentCountError.

```blade
{{-- resources/views/welcome.blade.php --}}
<x-icon name="camera" class="icon-lg" data-foo />
{{-- renders: <svg data-foo="1" class="icon icon-lg" ...>...</svg>
     (with 'icon' from the default global class config when set) --}}

<x-icon name="zondicon-flag" />
{{-- icons from a specific set: prefix is required --}}
```

--------------------------------

### Svg component usage examples

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Components.md

Example usage of per-icon components. Prefix is required, but the alias excludes the prefix group. Defer only works with components; fallback icons do not work with component syntax.

```blade
<x-icon-camera />
<x-icon-solid.camera class="w-6 h-6" id="settings-icon" data-baz/>
<x-zondicon-flag />

{{-- Deferred icon (replaces body with <use> and pushes to @stack('bladeicons')): --}}
<x-zondicon-flag defer />
<x-icon-camera defer="my-custom-hash" />

{{-- Accessibility: title attribute adds <title> and role="img" --}}
<x-icon-camera title="Camera" />
```

--------------------------------

### Handling CannotRegisterIconSet exception

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Error handling example for add() when the 'prefix' option is missing. The exception message is shown in a comment.

```php
use BladeUI\Icons\Exceptions\CannotRegisterIconSet;

try {
    $factory->add('broken', ['path' => 'resources/svg']); // no 'prefix'
} catch (CannotRegisterIconSet $e) {
    // "The options for the "broken" set don't have a prefix defined."
    report($e);
}
```

--------------------------------

### Example usage of IconGenerator::create

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Example of creating an IconGenerator with a single set configuration, specifying source, destination, input/output prefixes, input suffix, safe mode, and an after callback that receives the icon name, config, and SplFileInfo. The generate() method is then called.

```php
use BladeUI\Icons\Generation\IconGenerator;

IconGenerator::create([
    [
        'source' => __DIR__.'/../node_modules/heroicons/outline',
        'destination' => __DIR__.'/../resources/svg',
        'input-prefix' => 'o-',
        'output-prefix' => 'o-',
        'input-suffix' => '-outline',
        'safe' => true,
        'after' => function (string $icon, array $config, SplFileInfo $file) {
            // mutate $icon contents...
        },
    ],
])->generate();
```

--------------------------------

### Install Blade Icons with Composer

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Install the Blade Icons package via Composer. Requires PHP 7.4 or higher and Laravel 8.0 or higher.

```bash
composer require blade-ui-kit/blade-icons
```

--------------------------------

### Example: fluent attribute chaining

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/RendersAttributes.md

Demonstrates the fluent API: chaining __call methods to set attributes, including a bare attribute (dataBaz) that renders without a value.

```php
$icon = app(\BladeUI\Icons\Factory::class)->svg('camera');

$icon->class('icon-lg')->id('settings-icon')->style('color: #555')->dataFoo('bar')->dataBaz();

echo $icon->toHtml();
// '<svg class="icon-lg" id="settings-icon" style="color: #555" data-foo="bar" data-baz>...</svg>'
```

--------------------------------

### Example manifest value

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/types.md

Example manifest value matching the shape in tests/fixtures/generated-manifest.php. Keys are normalized absolute paths; values are sorted icon names with .svg stripped and directory separators converted to dots.

```php
[
    'default' => [
        '/abs/path/resources/svg' => [
            'camera',
            'foo-camera',
            'solid.camera',
            'zondicon-flag',
        ],
    ],
]
```

--------------------------------

### Example: attributes() with bare attribute

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/RendersAttributes.md

Shows how attributes() returns the attribute map after a zero-argument __call appends a bare attribute with a numeric key.

```php
$icon = $factory->svg('camera', ['class' => 'w-6']);
$icon->dataFoo();
var_export($icon->attributes());
// ['class' => 'w-6', 0 => 'data-foo']
```

--------------------------------

### Example: using addTitle()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Example usage of addTitle(). Creates an Svg instance and adds a title, resulting in '<svg><title>Camera</title></svg>' and setting attributes['role'] to 'img'.

```php
$svg = new Svg('camera', '<svg></svg>');
echo $svg->addTitle('Camera');
// '<svg><title>Camera</title></svg>'  (and attributes['role'] === 'img' afterwards)
```

--------------------------------

### Example: renderAttributes via Svg::toHtml()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/RendersAttributes.md

Shows renderAttributes via Svg::toHtml(): a string key renders as class="icon", an integer key (bare attribute) renders as just data-foo.

```php
$icon = new \BladeUI\Icons\Svg('camera', '<svg></svg>', ['class' => 'icon', 'data-foo']);
echo $icon->toHtml();
// '<svg class="icon" data-foo></svg>'
```

--------------------------------

### Catch CannotRegisterIconSet from Factory::add()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/errors.md

Shows how to catch CannotRegisterIconSet when calling Factory::add(). The example triggers the nonExistingPath case by passing a non-existent path; catching the class covers all four failure cases, and you must inspect the message to distinguish them because no machine-readable code is defined.

```php
use BladeUI\Icons\Exceptions\CannotRegisterIconSet;

try {
    $factory->add('icons', ['path' => 'resources/does-not-exist', 'prefix' => 'icon']);
} catch (CannotRegisterIconSet $e) {
    Log::error('Icon set registration failed', ['message' => $e->getMessage()]);
}
```

--------------------------------

### toHtml() accessibility example

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Accessibility example of toHtml() with a title attribute, which embeds a <title> element and adds role="img".

```php
$icon = $factory->svg('camera', ['title' => 'Camera']);
echo $icon->toHtml();
// '<svg title="Camera" role="img" ...><title>Camera</title>...</svg>'
```

--------------------------------

### icons:cache error when cache directory not writable

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Error handling example for icons:cache when the bootstrap/cache directory is not writable. The command fails with the shown error message.

```bash
# When bootstrap/cache is not writable:
# "The /path/to/bootstrap/cache directory must be present and writable."
php artisan icons:cache
```

--------------------------------

### Full source of blade-icons-generate binary

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Complete PHP source for the binary. It creates an IconGenerator with the configuration from the current working directory, prints start and finish messages, and returns Command::SUCCESS.

```php
#!/usr/bin/env php
<?php

use BladeUI\Icons\Generation\IconGenerator;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\SingleCommandApplication as Command;

if (file_exists(__DIR__.'/../vendor/autoload.php')) {
    require __DIR__.'/../vendor/autoload.php';
} else {
    require __DIR__.'/../../../autoload.php';
}

return (new Command)->setCode(function (InputInterface $input, OutputInterface $output) {
    $output->writeln("Starting to generate icons...");

    IconGenerator::create(
        require getcwd().'/config/generation.php'
    )->generate();

    $output->writeln("Finished generating icons!");

    return Command::SUCCESS;
})->run();
```

--------------------------------

### Error handling for svg()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Error handling example for `svg()`. Catches `SvgNotFound` and returns a 404 response. The comment shows the exception message format.

```php
use BladeUI\Icons\Exceptions\SvgNotFound;

try {
    $factory->svg('nonexistent');
} catch (SvgNotFound $e) {
    // 'Svg by name "nonexistent" from set "default" not found.'
    return response('missing icon', 404);
}
```

--------------------------------

### Handle SvgNotFound exception with svg() helper

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/helpers.md

Error handling example for the svg() helper. Catches SvgNotFound exception when the icon is missing and no fallback is configured. The exception message is shown in the comment.

```blade
{{-- Fallbacks are configured in config/blade-icons.php; without them: --}}
@php
    try {
        $icon = svg('missing-icon');
    } catch (\BladeUI\Icons\Exceptions\SvgNotFound $e) {
        $icon = null; // 'Svg by name "missing-icon" from set "default" not found.'
    }
@endphp

```

--------------------------------

### Register icon set with BladeUI\Icons\Factory and usage examples

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Register an icon set in a package's service provider using the BladeUI\Icons\Factory. The 'add' method requires a unique set name, a path to the SVG files, and a component prefix. After registration, icons can be referenced via the component, directive, or helper as shown.

```php
use BladeUI\Icons\Factory;

public function register(): void
{
    $this->callAfterResolving(Factory::class, function (Factory $factory) {
        $factory->add('heroicons', [
            'path' => __DIR__.'/../resources/svg',
            'prefix' => 'heroicon',
        ]);
    });
}
```

```blade
<x-heroicon-o-bell/>

@svg('heroicon-o-bell')

{{ svg('heroicon-o-bell') }}
```

--------------------------------

### Instantiate IconsManifest with dependencies

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Shows how to create an IconsManifest instance with a Filesystem, a manifest path, and the filesystem factory from the container.

```php
use BladeUI\Icons\IconsManifest;
use Illuminate\Filesystem\Filesystem;

$manifest = new IconsManifest(
    new Filesystem,
    base_path('bootstrap/cache/blade-icons.php'),
    app(\Illuminate\Contracts\Filesystem\Factory::class),
);
```

--------------------------------

### new Factory()

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Creates a new Factory instance with the required filesystem, manifest, optional filesystem manager, and configuration array.

```APIDOC
## Constructor

### Description
Creates a new Factory instance with the required filesystem, manifest, optional filesystem manager, and configuration array.

### Method
Constructor

### Signature
```php
public function __construct(
    Filesystem $filesystem,
    IconsManifest $manifest,
    ?FilesystemFactory $disks = null,
    array $config = []
)
```

### Parameters
- **$filesystem** (Illuminate\Filesystem\Filesystem) - Required - Local filesystem used for icon reads and (when $disks is null) disk reads.
- **$manifest** (BladeUI\Icons\IconsManifest) - Required - Manifest reader used by registerComponents() to enumerate icons.
- **$disks** (?Illuminate\Contracts\Filesystem\Factory) - Optional - Filesystem manager for sets that define a disk option. When null (or when a set has no disk), the local $filesystem is used.
- **$config** (array) - Optional - The resolved blade-icons config array. Normalized in the constructor: class → '', attributes → [], fallback → '', components.disabled → false, components.default → 'icon'.

### Example
```php
use BladeUI\Icons\Factory;
use BladeUI\Icons\IconsManifest;
use Illuminate\Filesystem\Filesystem;

$factory = new Factory(
    new Filesystem,
    new IconsManifest(new Filesystem, base_path('bootstrap/cache/blade-icons.php')),
    $app->make(\Illuminate\Contracts\Filesystem\Factory::class),
    ['class' => 'icon icon-default'],
);
```
```

--------------------------------

### applyPrefixes method

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Applies input and output prefixes to the filename. If 'input-prefix' is set, strips it from the source name using after(). If 'output-prefix' is set, prepends it to the filename.

```php
// No code block provided in source for this method.
```

--------------------------------

### Create and run IconGenerator with config

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Creates an IconGenerator instance using the configuration file and calls generate(). Errors like a missing source directory surface as FileNotFoundException from the framework.

```php
$generator = IconGenerator::create(require base_path('config/generation.php'));
$generator->generate();
```

--------------------------------

### boot(): void method signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/BladeIconsServiceProvider.md

The public boot method of the service provider. It runs four private boot steps: bootCommands, bootDirectives, bootIconComponent, and bootPublishing.

```php
public function boot(): void
```

--------------------------------

### bootPublishing(): void - publish config file

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/BladeIconsServiceProvider.md

Publishes the config file to config/blade-icons.php when running in console, enabling php artisan vendor:publish --tag=blade-icons.

```php
if ($this->app->runningInConsole()) {
    $this->publishes([
        __DIR__.'/../config/blade-icons.php' => $this->app->configPath('blade-icons.php'),
    ], 'blade-icons');
}
```

--------------------------------

### write(array $sets): void

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Builds and writes the manifest file atomically, throwing an exception if the directory is not writable.

```APIDOC
## write(array $sets): void

### Description
Builds the manifest from the given sets, memoizes it, and atomically replaces the manifest file with a PHP return statement. Used by the `icons:cache` command.

### Method
PHP method

### Endpoint
`write(array $sets): void`

### Parameters
#### Parameters
- **$sets** (array) - Required - The sets to build the manifest from.

### Throws
`Exception` when the directory of the manifest path is not present or writable.

### Example
```php
$manifest->write($factory->all());
// writes bootstrap/cache/blade-icons.php
```

### Error Handling
```php
use Exception;

try {
    $manifest->write($factory->all());
} catch (Exception $e) {
    // 'The /path/to/bootstrap/cache directory must be present and writable.'
}
```
```

--------------------------------

### Generated SVG with title attribute

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Example result of an icon with a title attribute, showing the generated SVG structure including the title element, role="img", and aria-labelledby.

```html
<svg 
	 title="Camera" 
	 role="img" 
	 xmlns="http://www.w3.org/2000/svg"
	 viewBox="0 0 448 512"
>
	<title>
		Camera
	</title>
	<path fill="currentColor" d="M438.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-160-160c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L338.8 224 32 224c-17.7 0-32 14.3-32 32s14.3 32 32 32l306.7 0L233.4 393.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0l160-160z"></path>
</svg>  
```

--------------------------------

### IconsManifest::__construct

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Constructs an IconsManifest instance with the required filesystem and manifest path, and an optional filesystem manager for disk-based icon sets.

```APIDOC
## Constructor

### Description
Initializes a new IconsManifest instance with the filesystem, manifest path, and optional filesystem manager.

### Method
Constructor

### Signature
`public function __construct(Filesystem $filesystem, string $manifestPath, ?FilesystemFactory $disks = null)`

### Parameters
- **$filesystem** (Illuminate\Filesystem\Filesystem) - Required - Local filesystem used for manifest file reads/writes/deletes and (when $disks is null) directory scans.
- **$manifestPath** (string) - Required - Absolute path to the manifest PHP file (e.g. bootstrap/cache/blade-icons.php).
- **$disks** (?Illuminate\Contracts\Filesystem\Factory) - Optional - Filesystem manager used to scan sets that define a disk option; when null the local filesystem is used.

### Example
```php
use BladeUI\Icons\IconsManifest;
use Illuminate\Filesystem\Filesystem;

$manifest = new IconsManifest(
    new Filesystem,
    base_path('bootstrap/cache/blade-icons.php'),
    app(\Illuminate\Contracts\Filesystem\Factory::class),
);
```
```

--------------------------------

### name(): string

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Returns the icon name passed to the constructor.

```APIDOC
## `name(): string`

### Description
Returns the icon name passed to the constructor (`$this->name`).

### Method
`name`

### Signature
```php
public function name(): string
```

### Return
- **string** - The icon name.

### Example
```php
$factory = app(\BladeUI\Icons\Factory::class);
$icon = $factory->svg('zondicon-flag');
echo $icon->name(); // 'flag'
```
```

--------------------------------

### Factory singleton binding

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/BladeIconsServiceProvider.md

Binds the Factory as a singleton. For sets without a disk, relative paths are resolved against the application base path; sets with a disk keep paths as-is. All configured sets are added immediately, so configuration errors surface at container resolution.

```php
$this->app->singleton(Factory::class, function (Application $app) {
    $config = $app->make('config')->get('blade-icons', []);

    $factory = new Factory(
        new Filesystem,
        $app->make(IconsManifest::class),
        $app->make(FilesystemFactory::class),
        $config,
    );

    foreach ($config['sets'] ?? [] as $set => $options) {
        if (! isset($options['disk']) || ! $options['disk']) {
            $paths = $options['paths'] ?? $options['path'] ?? [];

            $options['paths'] = array_map(
                fn ($path) => $app->basePath($path),
                (array) $paths,
            );
        }

        $factory->add($set, $options);
    }

    return $factory;
});
```

--------------------------------

### Catch SvgNotFound and return 404 view

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/errors.md

Catches SvgNotFound when calling svg() with an unknown icon name. The example uses 'heroicon-nope' and returns a 404 view with the message 'Svg by name "nope" from set "heroicon" not found.' This catch block is useful for handling missing icons gracefully.

```php
use BladeUI\Icons\Exceptions\SvgNotFound;

try {
    $icon = svg('heroicon-nope');
} catch (SvgNotFound $e) {
    // 'Svg by name "nope" from set "heroicon" not found.'
    return Response::view('icon-missing', status: 404);
}
```

--------------------------------

### Configure icon generation with generation.php and run blade-icons-generate

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Define a generation.php config file for generating icons. Only 'source' and 'destination' are required; other options are optional. After setting up the config, run the blade-icons-generate command from the root of your icon package directory.

```php
<?php

use Symfony\Component\Finder\SplFileInfo;

return [
    [
        // Define a source directory for the sets like a node_modules/ or vendor/ directory...
        'source' => __DIR__.'/../node_modules/heroicons/outline',

        // Define a destination directory for your icons. The below is a good default...
        'destination' => __DIR__.'/../resources/svg',

        // Strip an optional prefix from each source icon name...
        'input-prefix' => 'o-',

        // Set an optional prefix to applied to each destination icon name...
        'output-prefix' => 'o-',

        // Strip an optional suffix from each source icon name...
        'input-suffix' => '-o',

        // Set an optional suffix to applied to each destination icon name...
        'output-suffix' => '-o',

        // Enable "safe" mode which will prevent deletion of old icons...
        'safe' => true,

        // Call an optional callback to manipulate the icon with the pathname of the icon,
        // the settings from above and the original icon file instance...
        'after' => static function (string $icon, array $config, SplFileInfo $file) {
            // ...
        },
    ],

    // More icon sets...
];
```

```zsh
vendor/bin/blade-icons-generate
```

--------------------------------

### Use @svg directive in Blade templates

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/helpers.md

Examples of using the @svg directive in Blade templates. Shows passing classes, attributes, attributes as second argument, overriding default classes, attributes without keys, and prefixing for non-default sets. Note: the defer attribute does not work with the directive; prefixed names are required for non-default sets.

```blade
@svg('camera', 'icon-lg')

@svg('camera', 'icon-lg', ['id' => 'settings-icon'])

@svg('camera', ['id' => 'settings-icon'])  {{-- attributes as second argument --}}

@svg('camera', ['class' => 'icon-lg'])     {{-- overrides default classes --}}

@svg('camera', ['data-foo'])               {{-- attributes without keys --}}

{{-- Prefix required for non-default sets --}}
@svg('zondicon-flag')

```

--------------------------------

### Import Illuminate\Support\Str

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/RendersAttributes.md

Imports the Str class from Illuminate\Support, used for converting camelCase method names to dash-case attribute names.

```php
use Illuminate\Support\Str;
```

--------------------------------

### Constructor signature for IconGenerator

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Constructor accepts an array of icon-set generation configurations. Each element requires 'source' and 'destination' keys, with optional 'safe', 'input-prefix', 'output-prefix', 'input-suffix', 'output-suffix', and 'after' keys.

```php
public function __construct(array $sets)
```

--------------------------------

### Private implementation method signatures

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Internal method signatures for building the manifest, scanning local and disk files, selecting filesystem, and formatting paths. These are private and not part of the public API.

```php
private function build(array $sets): array            // src/IconsManifest.php:33
private function scanLocal(string $path): array       // :63
private function scanDisk(string $disk, string $path): array // :95
private function filesystem(?string $disk = null)     // :121
private function format(string $pathname, string $path): string // :131
```

--------------------------------

### add() method signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Signature of the add method. Throws CannotRegisterIconSet when validation fails.

```php
public function add(string $set, array $options): self
```

--------------------------------

### add(string $set, array $options): self

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Adds or replaces an icon set in the registry. Validates options, normalizes paths, and clears the cache.

```APIDOC
## `add(string $set, array $options): self`

### Description
Adds or replaces an icon set in the registry (keyed by `$set`). Validates the options, trims trailing slashes from paths, checks path existence, then stores the set and clears the in-memory contents cache.

### Method
`add`

### Signature
```php
public function add(string $set, array $options): self
```

### Parameters
- **$set** (string) - Required - The name of the icon set to add or replace.
- **$options** (array) - Required - An associative array of options. Supported keys:
  - `prefix` (string) - Required - The prefix for the icon set. Must be unique among all sets.
  - `paths` (array) - Optional - An array of paths to SVG files. If both `paths` and `path` are provided, `paths` wins.
  - `path` (string|array) - Optional - A single path or array of paths. If a string, it is cast to a one-element array. This key is unset after normalization; the stored set always uses `paths`.
  - `class` (string) - Optional - Default CSS class for icons in this set.
  - `fallback` (string) - Optional - Fallback icon name.
  - `attributes` (array) - Optional - Default HTML attributes for icons.

### Return Value
- **self** - Returns the factory instance for chaining.

### Throws
- `CannotRegisterIconSet::prefixNotDefined($set)` - When `$options['prefix']` is not set.
- `CannotRegisterIconSet::prefixNotUnique($set, $collidingSet)` - When another already-added set uses the same `prefix`.
- `CannotRegisterIconSet::pathsNotDefined($set)` - When, after resolving `paths`/`path` and filtering empty values, there are no paths.
- `CannotRegisterIconSet::nonExistingPath($set, $path)` - When a path (other than `/`) does not exist on the resolved filesystem.

### Behavior Details
- Paths resolution: `$paths = (array) ($options['paths'] ?? $options['path'] ?? []);` — `paths` wins over `path`; a string `path` is cast to a one-element array.
- Trailing slashes stripped except for `'/'`: `$path !== '/' ? rtrim($path, '/') : $path`.
- `$options['path']` is unset after normalization; the stored set always uses a `paths` key.
- Path existence check is skipped for `'/'` (typical root path on a disk).
- Existing sets with the same `$set` name are overwritten; the in-memory `$cache` is reset so re-reads pick up new contents.

### Example
```php
$factory->add('heroicons', [
    'path' => __DIR__.'/../resources/svg',
    'prefix' => 'heroicon',
    'class' => 'heroicon',
    'fallback' => 'o-x-circle',
    'attributes' => ['width' => 24],
]);

$factory->add('multi', [
    'paths' => ['resources/svg/a', 'resources/svg/b'], // wins over 'path'
    'prefix' => 'multi',
]);
```

### Error Handling
```php
use BladeUI\Icons\Exceptions\CannotRegisterIconSet;

try {
    $factory->add('broken', ['path' => 'resources/svg']); // no 'prefix'
} catch (CannotRegisterIconSet $e) {
    // "The options for the \"broken\" set don't have a prefix defined."
    report($e);
}
```
```

--------------------------------

### __construct(array $sets)

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Constructor for the IconGenerator class. It accepts an array of icon-set generation configurations and creates an internal Filesystem instance.

```APIDOC
## `__construct(array $sets)`

### Description
Creates a new IconGenerator instance with the given icon-set generation configurations.

### Method
Constructor

### Parameters
- **$sets** (array) - Required - Array of icon-set generation configurations. Each element holds `source` and `destination` (required) plus the optional `safe`, `input-prefix`, `output-prefix`, `input-suffix`, `output-suffix`, and `after` keys.

### Return
No return value.
```

--------------------------------

### blade-icons-generate binary usage

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Command to run the binary from the root of an icon package. Executes the generation process using the configuration file in the current working directory.

```zsh
# run from the root of your icon package
vendor/bin/blade-icons-generate
```

--------------------------------

### Implement renderAttributes() logic

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/RendersAttributes.md

Implementation of renderAttributes: returns '' for empty attributes; integer keys render as bare values, string keys as name="value". Joined with single spaces and prefixed with a leading space.

```php
if (count($this->attributes) == 0) {
    return '';
}

return ' '.collect($this->attributes)->map(function (string $value, $attribute) {
    if (is_int($attribute)) {
        return $value;
    }

    return sprintf('%s="%s"', $attribute, $value);
})->implode(' ');
```

--------------------------------

### Use an external filesystem disk for the default set

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Configures the default set to load icons from an external filesystem disk (e.g., an AWS S3 bucket) defined in 'filesystems.php'. The path is set to '/' because icons are stored in the root of the bucket.

```php
<?php

return [
    'sets' => [
        'default' => [
            'path' => '/',
            'disk' => 's3-icons',
        ],
    ],
];
```

--------------------------------

### bootCommands(): void - register console commands

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/BladeIconsServiceProvider.md

Registers console commands when running in console. If the framework supports optimizes() (Laravel 11+), registers icons:cache and icons:clear as framework optimizations.

```php
if ($this->app->runningInConsole()) {
    $this->commands([
        Console\CacheCommand::class,
        Console\ClearCommand::class,
    ]);

    if (method_exists($this, 'optimizes')) {
        $this->optimizes(
            'icons:cache',
            'icons:clear',
            'blade-icons'
        );
    }
}
```

--------------------------------

### Constructor signature for IconsManifest

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Defines the constructor of IconsManifest, which accepts a Filesystem instance, a manifest path, and an optional FilesystemFactory for disk-based sets.

```php
public function __construct(Filesystem $filesystem, string $manifestPath, ?FilesystemFactory $disks = null)
```

--------------------------------

### getDestinationDirectory method

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Returns the destination directory after ensuring it exists. When 'safe' is falsy (default), deletes the entire destination directory before regeneration to remove stale icons. The returned path always ends with a directory separator.

```php
$destination = Str::finish($set['destination'], DIRECTORY_SEPARATOR);

if (! Arr::get($set, 'safe', false)) {
    $this->filesystem->deleteDirectory($destination);
}

$this->filesystem->ensureDirectoryExists($destination);

return $destination;
```

--------------------------------

### all(): array method

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Factory.md

Returns the raw internal `$sets` array: `array<string set_name, array set_options>` where each set's options are the stored (normalized) options — always containing at least `prefix` and `paths`. Marked `@internal` in the source; used by `IconsManifest::write()` and `Console\CacheCommand`.

```php
/**
 * @internal This method is only meant for internal purposes and does not fall under the package's BC promise.
 */
public function all(): array
```

--------------------------------

### Imports for IconGenerator

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconGenerator.md

Imports the Filesystem, Arr, Str, Stringable, and SplFileInfo classes used by the IconGenerator.

```php
use Illuminate\Filesystem\Filesystem;
use Illuminate\Support\Arr;
use Illuminate\Support\Str;
use Illuminate\Support\Stringable;
use Symfony\Component\Finder\SplFileInfo;
```

--------------------------------

### Clear Views with view:clear

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Clear compiled views. Recommended after adding new icons or renaming directories in icon paths to ensure changes are reflected.

```bash
php artisan view:clear
```

--------------------------------

### Factory constructor signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/configuration.md

Constructor for the Factory class. Accepts Filesystem, IconsManifest, optional FilesystemFactory, and config array. The config array should be the already-resolved blade-icons config. Defaults when config is empty: class='', attributes=[], fallback='', components.disabled=false, components.default='icon'.

```php
public function __construct(
    Filesystem $filesystem,
    IconsManifest $manifest,
    ?FilesystemFactory $disks = null,
    array $config = []
)
```

--------------------------------

### ClearCommand handle method signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Signature of the handle method for ClearCommand. It receives the IconsManifest instance.

```php
public function handle(IconsManifest $manifest): int
```

--------------------------------

### Function signatures for svg(), Factory, Icon, and Svg

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/types.md

Exact function signatures from the source files. Use these to understand the expected parameters and return types when calling the svg() helper or Factory methods, or when extending the Icon and Svg components.

```php
// src/helpers.php
function svg(string $name, $class = '', array $attributes = []): Svg

// src/Factory.php
public function add(string $set, array $options): self
public function svg(string $name, $class = '', array $attributes = []): Svg

// src/Components/Icon.php
public function __construct(string $name)
public function render(): Closure   // closure: function (array $data): string

// src/Components/Svg.php
public function render(): Closure   // closure: function (array $data): string
```

--------------------------------

### CacheCommand handle body

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Body of CacheCommand::handle(). Writes the manifest for all registered sets to bootstrap/cache/blade-icons.php, prints a success message, and returns exit code 0. Throws an exception if the cache directory is not writable.

```php
$manifest->write($factory->all());

$this->info('Blade icons manifest file generated successfully!');

return 0;
```

--------------------------------

### Constructor defaults for top-level config options

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/configuration.md

Shows the default values enforced in Factory::__construct() for the top-level configuration keys: class, attributes, fallback, and components. These defaults are applied when the corresponding config keys are not set.

```php
$this->config['class'] = $config['class'] ?? '';
$this->config['attributes'] = (array) ($config['attributes'] ?? []);
$this->config['fallback'] = $config['fallback'] ?? '';
$this->config['components'] = [
    'disabled' => $config['components']['disabled'] ?? false,
    'default' => $config['components']['default'] ?? 'icon',
];
```

--------------------------------

### Define multiple paths for an icon set

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Defines multiple paths for a single set using the 'paths' option. Icons from all paths are grouped under one set with the same prefix and default classes. When an icon name exists in more than one path, the first found icon is returned.

```php
<?php

return [
    'sets' => [
        'default' => [
            'paths' => [
                'resources/images/icon-set',
                'resources/images/other-icon-set',
            ],
        ],
    ],
];
```

--------------------------------

### Icon component imports

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Components.md

Imports the Closure and base Component classes used by the Icon component.

```php
use Closure;
use Illuminate\View\Component;
```

--------------------------------

### CacheCommand handle method signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Signature of the handle method for CacheCommand. It receives the Factory and IconsManifest instances.

```php
public function handle(Factory $factory, IconsManifest $manifest): int
```

--------------------------------

### ClearCommand handle body

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Body of ClearCommand::handle(). Deletes the manifest file via IconsManifest::delete(), prints a success message, and returns exit code 0. Deleting a non-existent file is safe.

```php
$manifest->delete();

$this->info('Blade icons manifest file cleared!');

return 0;
```

--------------------------------

### Set a custom icon path for the default set

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Changes the default set's path to a different directory, e.g., 'resources/images/svg'. Ensure the directory exists before using this configuration.

```php
<?php

return [
    'sets' => [
        'default' => [
            'path' => 'resources/images/svg',
        ],
    ],
];
```

--------------------------------

### Define multiple sets on the same disk

Source: https://github.com/driesvints/blade-icons/blob/1.x/README.md

Defines multiple icon sets on the same external disk, each with its own path and unique prefix. This allows grouping icons from different directories on the same disk.

```php
<?php

return [
    'sets' => [
        'heroicons' => [
            'path' => 'heroicons',
            'disk' => 's3-icons',
            'prefix' => 'heroicon',
        ],
        'zondicons' => [
            'path' => 'zondicons',
            'disk' => 's3-icons',
            'prefix' => 'zondicon',
        ],
    ],
];
```

--------------------------------

### Register icons:cache and icons:clear commands

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/ConsoleCommands.md

Registers the icons:cache and icons:clear Artisan commands in BladeIconsServiceProvider::bootCommands(). Only exposed when running in console.

```php
$this->commands([
    Console\CacheCommand::class,
    Console\ClearCommand::class,
]);
```

--------------------------------

### Icon constructor signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Components.md

Constructor for the Icon component. Requires the icon name, which may include a set prefix and dot notation (e.g., 'zondicon-flag', 'solid.camera').

```php
public function __construct(string $name)
```

--------------------------------

### Using the fluent attribute API on Svg

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Shows the fluent API from RendersAttributes: zero-arg calls append bare attributes (dataBaz() → data-baz) and one-arg calls set snake-case attributes (class('icon-lg') → class="icon-lg"). The output is a rendered SVG string.

```php
$icon = $factory->svg('camera');
$icon->class('icon-lg')->id('settings-icon')->dataBaz();
echo $icon->toHtml(); // '<svg class="icon-lg" id="settings-icon" data-baz></svg>'
```

--------------------------------

### Imports for IconsManifest

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Imports the necessary classes used within the IconsManifest class file.

```php
use Exception;
use FilesystemIterator;
use Illuminate\Contracts\Filesystem\Factory as FilesystemFactory;
use Illuminate\Filesystem\Filesystem;
use Illuminate\Support\Str;
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
use Symfony\Component\Finder\SplFileInfo;
```

--------------------------------

### IconsManifest singleton binding

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/BladeIconsServiceProvider.md

Binds the IconsManifest as a singleton using the manifest path returned by manifestPath(), which is bootstrap/cache/blade-icons.php.

```php
$this->app->singleton(IconsManifest::class, function (Application $app) {
    return new IconsManifest(
        new Filesystem,
        $this->manifestPath(),
        $app->make(FilesystemFactory::class),
    );
});
```

--------------------------------

### deferContent() method signature

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/Svg.md

Signature of the internal deferContent() helper that generates deferred-icon output.

```php
protected function deferContent(string $contents, $defer = false): string
```

--------------------------------

### write method signature with docblock

Source: https://github.com/driesvints/blade-icons/blob/1.x/_autodocs/api-reference/IconsManifest.md

Public method signature for write that takes an array of sets and returns void. Includes a @throws Exception docblock indicating it can throw an exception.

```php
/**
 * @throws Exception
 */
public function write(array $sets): void
```
Tokens:
Raw