frostybee/swarm-icons

Framework-agnostic PHP SVG icon library with first-class Twig support and Iconify API integration

v1.2.0 2026-02-28 23:19 UTC

Requires

• php: ^8.2
• psr/simple-cache: ^3.0
• symfony/console: ^6.4|^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• league/commonmark: ^2.0
• phpstan/phpstan: ^1.10
• phpstan/phpstan-strict-rules: ^1.5
• phpunit/phpunit: ^10.5
• symfony/var-dumper: ^6.4|^7.0
• twig/twig: ^3.0

Suggests

• iconify/json: Install to use JsonCollectionProvider for offline access to 200,000+ icons
• twig/twig: For Twig template integration (^3.0)

MIT

• frostybee

• twig
• icons
• svg
• iconify
• Heroicons
• lucide
• bootstrap-icons
• tabler-icons
• simple-icons
• Phosphor

README

Swarm Icons

A Framework-Agnostic PHP Library for Rendering SVG Icons

Features

• Access 200,000+ icons from 200+ Iconify sets, downloadable via CLI (no Node.js required)
• Load icons from local SVG directories, the Iconify API, JSON collections, or a hybrid of local files with API fallback
• Style icons with an immutable fluent API: size(), class(), fill(), stroke(), rotate(), flip(), and more
• Integrates with Twig, Laravel Blade, Slim, and CommonMark
• Deduplicate repeated icons on a page using SVG sprite sheets with <symbol> / <use> references
• Layer multiple icons into a single composite SVG with icon stacking
• Decorative icons get aria-hidden="true" automatically; labeled icons get role="img"
• SVG content is sanitized: scripts, event handlers, and external resources are stripped
• PSR-16 file-based caching with configurable TTL

Installation

composer require frostybee/swarm-icons

Requires PHP 8.2+ and psr/simple-cache ^3.0.

Quick Start

Download icon sets and render:

php bin/swarm-icons json:download mdi tabler heroicons

use Frostybee\SwarmIcons\SwarmIcons;
use Frostybee\SwarmIcons\SwarmIconsConfig;

$manager = SwarmIconsConfig::create()
    ->discoverJsonSets()
    ->cachePath('/var/cache/icons')
    ->build();

SwarmIcons::setManager($manager);

echo swarm_icon('mdi:home', ['class' => 'w-6 h-6']);
// <svg class="w-6 h-6" aria-hidden="true">...</svg>

You can also register local SVG directories or fetch from the Iconify API at runtime:

$manager = SwarmIconsConfig::create()
    ->addDirectory('custom', '/path/to/svgs')
    ->addIconifySet('heroicons')
    ->defaultAttributes(['class' => 'icon'])
    ->prefixAttributes('heroicons', ['stroke' => 'currentColor'])
    ->fallbackIcon('heroicons:question-mark-circle')
    ->build();

Documentation

For detailed guides on configuration, providers, CLI commands, framework integrations, and advanced options, visit the full documentation.

Development

composer install

Command	Description
composer test	Run PHPUnit tests
composer phpstan	Run PHPStan (level 8)
composer cs-check	Check code style (dry-run)
composer cs-fix	Auto-fix code style
composer test-all	PHPStan + CS check + tests

License

This project is licensed under the MIT License. See LICENSE for details.