Advanced Options

These features aren’t needed for every project, but they’re useful as your icon usage grows, especially when working with dynamic icon names, large teams, or third-party packages.

Aliases

If you find yourself typing heroicons:check-circle over and over, give it a shorter name:

->alias('check', 'heroicons:check-circle')
->alias('dots',  'clarity:ellipsis-horizontal-line')
->alias('close', 'heroicons:x-mark')

Now you can use the alias anywhere you’d use the full name:

echo swarm_icon('check');
echo swarm_icon('close', ['class' => 'w-4 h-4']);
$manager->has('dots'); // true

Aliases are resolved before prefix parsing, so they work transparently with get(), has(), and the swarm_icon() helper.

A few things to keep in mind:

The target must be a full prefix:name string
Only one level of indirection: you can’t alias to another alias
Calling ->alias() twice with the same key overwrites the first mapping

You can inspect what’s registered at runtime with $manager->getAliases().

Fallback icon

When a requested icon doesn’t exist, Swarm Icons throws IconNotFoundException by default. If you’d rather show a placeholder, set a fallback:

->fallbackIcon('heroicons:question-mark-circle')

Pick something from a set you know is always available (a downloaded JSON set or a local directory that ships with your project).

Suppressing exceptions with `ignoreNotFound`

For cases where you’d rather render nothing than throw, enable ignoreNotFound:

->ignoreNotFound()

Missing icons will return an empty Icon that renders as an empty string. No exception, no visible output.

The two-layer safety net

fallbackIcon and ignoreNotFound work well together. The fallback is tried first: if it also fails, ignoreNotFound catches it silently:

->fallbackIcon('tabler:question-mark')
->ignoreNotFound()

echo swarm_icon('tabler:nonexistent');
// 1. Icon not found → tries fallback 'tabler:question-mark'
// 2. Fallback found → renders the question mark icon

If the fallback itself were also missing (unlikely, but possible), the icon would render as an empty string instead of throwing. This gives you a visible placeholder in normal cases and a silent fallback for edge cases.

In templates, this means you never need try/catch:

echo swarm_icon('might-not-exist');
// Either the fallback icon, or '': never an exception

Per-prefix fallbacks

The global fallbackIcon() applies to all prefixes. If you need different placeholders per icon set, use fallbackIconForPrefix():

SwarmIconsConfig::create()
    ->fallbackIcon('heroicons:question-mark-circle')                  // global default
    ->fallbackIconForPrefix('tabler', 'tabler:help')                  // tabler-specific
    ->fallbackIconForPrefix('mdi', 'mdi:help-circle-outline')         // mdi-specific
    ->build();

Resolution order when an icon is not found:

Per-prefix fallback (if set for that prefix)
Global fallback
Throw IconNotFoundException (or empty string if ignoreNotFound is enabled)

Suffix attributes

Some icon sets use naming conventions where a suffix indicates a variant. For example, Heroicons uses -solid and -outline suffixes. With prefixSuffix() you can automatically apply attributes based on the icon name’s suffix:

SwarmIconsConfig::create()
    ->prefixSuffix('heroicons', 'solid', ['fill' => 'currentColor', 'stroke' => 'none'])
    ->prefixSuffix('heroicons', 'outline', ['fill' => 'none', 'stroke' => 'currentColor', 'stroke-width' => '1.5'])
    ->build();

echo swarm_icon('heroicons:home-solid');
// fill="currentColor" stroke="none" applied automatically

echo swarm_icon('heroicons:home-outline');
// fill="none" stroke="currentColor" stroke-width="1.5" applied automatically

Default suffix rule

Pass an empty string as the suffix to define a fallback rule. It applies when no other suffix matches:

->prefixSuffix('heroicons', '', ['fill' => 'currentColor'])     // default
->prefixSuffix('heroicons', 'outline', ['fill' => 'none', 'stroke' => 'currentColor'])

Icons like heroicons:home (no recognized suffix) get the default rule. Icons like heroicons:home-outline get the outline rule.

Merge order

Suffix attributes sit between prefix defaults and caller attributes in the merge pipeline:

Icon defaults (from the SVG itself)
Global defaults (->defaultAttributes())
Prefix defaults (->prefixAttributes())
Suffix attributes (->prefixSuffix())
Caller attributes (passed to swarm_icon() or ->get())

Caller attributes always win. CSS classes are appended at every layer, never replaced.

Package discovery

If you’re building a Composer package that provides icons, you can make it auto-discoverable. Declare your provider in composer.json:

{
    "extra": {
        "swarm-icons": {
            "prefix": "myset",
            "provider-class": "Vendor\\MyIconSet"
        }
    }
}

The provider class implements IconSetInterface:

use Frostybee\SwarmIcons\IconSetInterface;
use Frostybee\SwarmIcons\IconManager;

class MyIconSet implements IconSetInterface
{
    public static function prefix(): string
    {
        return 'myset';
    }

    public static function register(IconManager $manager): void
    {
        $manager->register('myset', new DirectoryProvider(__DIR__ . '/icons'));
    }
}

Consumers of your package just add one line to their config:

->discoverPackages()

Both single-set (object) and multi-set (array) formats are supported in the extra.swarm-icons field.