Using Local SVG Files

If you have your own SVG files (custom icons, brand assets, or designer exports), point Swarm Icons at the folder and you’re done.

Getting started

$manager = SwarmIconsConfig::create()
    ->addDirectory('custom', __DIR__ . '/resources/icons')
    ->build();

echo $manager->get('custom:home');   // loads resources/icons/home.svg
echo $manager->get('custom:close');  // loads resources/icons/close.svg

The first argument is the prefix: a name you choose. The second is the path to your SVG directory. That’s all it takes.

How names map to files

The icon name (the part after the :) maps directly to a filename, minus the .svg extension:

$manager->get('custom:home');        // → home.svg
$manager->get('custom:arrow-left');  // → arrow-left.svg

No magic, no transformation. The name is the filename.

Organizing with subdirectories

By default, the provider scans subdirectories recursively. Use / to reach icons inside them:

resources/icons/
├── home.svg
├── close.svg
├── outline/
│   ├── home.svg
│   └── user.svg
└── solid/
    ├── home.svg
    └── user.svg

echo $manager->get('icons:home');            // home.svg
echo $manager->get('icons:outline/home');    // outline/home.svg
echo $manager->get('icons:solid/user');      // solid/user.svg

This is useful for icon sets that ship variants in separate folders, like Heroicons with its outline/ and solid/ directories.

If you only want top-level files, disable the recursive scan:

->addDirectory('flat', '/path/to/icons', recursive: false)

Multiple directories

$manager = SwarmIconsConfig::create()
    ->addDirectory('app', __DIR__ . '/resources/icons')
    ->addDirectory('brand', __DIR__ . '/assets/brand')
    ->build();

echo $manager->get('app:logo');
echo $manager->get('brand:wordmark');

Security

DirectoryProvider guards against path traversal. Any icon name that would resolve outside the registered directory is rejected: requests like ../../../etc/passwd won’t load.

Listing what’s available

From PHP:

foreach ($manager->all('custom') as $name) {
    echo $name . "\n";   // home, close, outline/home, ...
}

Or from the CLI:

vendor/bin/swarm-icons icon:list --path=/path/to/svgs