Using Hybrid Provider

Sometimes you need icons from more than one source under the same prefix. The ChainProvider tries providers in sequence and returns the first match: perfect for layering local files with an API fallback.

The quick way

The builder has a shorthand that pairs a local directory with the Iconify API:

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

When you request an icon, it checks your local folder first. If the file isn’t there, it fetches from the Iconify API and caches the result. You get the best of both worlds: fast local resolution with automatic API coverage for anything you haven’t downloaded yet.

Building a custom chain

For more control, assemble the chain yourself. Providers are tried in the order you list them:

use Frostybee\SwarmIcons\Provider\ChainProvider;
use Frostybee\SwarmIcons\Provider\DirectoryProvider;
use Frostybee\SwarmIcons\Provider\IconifyProvider;
use Frostybee\SwarmIcons\Cache\FileCache;

$manager->register('icons', new ChainProvider([
    new DirectoryProvider('/path/to/overrides'),
    new DirectoryProvider('/path/to/base-icons'),
    new IconifyProvider('heroicons', new FileCache('/tmp/cache')),
]));

The first provider to find the icon wins. The rest are never asked.

When this is useful

Gradual migration: You’re moving from local SVGs to Iconify sets. Keep the old files on disk while the API fills in the gaps. Remove local files at your own pace:

->addHybridSet('icons', __DIR__ . '/legacy-icons')

Local overrides: Your designer tweaked a few icons from an Iconify set. Drop the custom SVGs in a folder and they take priority over the API versions:

new ChainProvider([
    new DirectoryProvider('/path/to/custom'),   // your home.svg wins
    new IconifyProvider('heroicons', $cache),    // everything else from API
]);

Offline resilience: Prefer the API for fresh data, but keep a local copy as insurance when the network is unavailable:

new ChainProvider([
    new IconifyProvider('tabler', $cache),
    new DirectoryProvider('/path/to/offline-fallback'),
]);

Choosing the right provider

	Local SVG	JSON Collections	Iconify API	Hybrid
Works offline	Yes	Yes	No	Partially
Setup effort	Copy SVG files	Run json:download	None	Copy SVGs
Icon catalog	Your files only	Downloaded sets	200,000+	Both
Best for	Custom icons	Production apps	Prototyping	Migration, overrides

For most production apps, JSON Collections are the simplest path: fast, offline, no moving parts. Hybrid shines when you need local overrides or are transitioning between icon sources.

See also

• Using Local SVG Files: loading icons from your own .svg files
• Using the Iconify API: fetching icons on demand over HTTP
• Using JSON Collections: the recommended approach for production