Ux Icons Laravel Package

Technical Evaluation

Architecture fit — Weak on paper, workable with a wrapper. symfony/ux-icons is a Symfony bundle, not a framework-agnostic package: it ships UXIconsBundle (extends Symfony\Component\HttpKernel\Bundle\Bundle), reads config/packages/ux_icons.yaml via the Symfony Config component, registers services in a Symfony DI container, resolves a PSR-6 CacheInterface (defaulting to cache.app), and hooks cache:warmup. Laravel has no bundle/kernel/config-tree concept, so "install and configure" becomes "build an adapter." The genuinely reusable core is the IconRenderer + IconRegistry + Iconify fetch/sanitize pipeline; the Twig-facing surface (ux_icon(), <twig:ux:icon />) is Symfony-UX-specific and does not work in Blade.

Integration feasibility — Three viable paths, in descending order of cost:

1. Full bundle inside Laravel — requires symfony/framework-bundle, a minimal Kernel, and a cache-contracts→Laravel-cache adapter. High blast radius for a rendering helper. Not recommended.
2. Standalone wiring (recommended if adopting) — register IconRenderer, IconRegistry, and the Iconify fetcher manually in a Laravel ServiceProvider, point them at a CacheInterface adapter over Laravel's cache, and expose a Blade component <x-icon name="mdi:check" /> plus a @icon(...) directive. Cost is roughly 2–4 weeks including tests; accept coupling to classes that may be marked @internal and pin exact versions.
3. Blade-only path — skip this package and use blade-ui-kit/blade-icons. Loses the sanitizer and Iconify-on-demand story but avoids all adapter risk.

Caveat if the team wants Twig in Laravel: rcrowe/twigbridge gives Twig, but Twig Components (<twig:ux:icon />) additionally need symfony/ux-twig-component runtime machinery — treat the component syntax as out of scope; standardize on the function or a Blade component.

Technical risk

• Security (highest) — CVE-2026-55877 (fixed in 3.2.0 / 2.36.1) covers XSS via unsanitized Iconify SVG bodies and local files. Pin >=3.2.0 (or >=2.36.1) as a hard gate and require composer audit in CI. Note the fix keeps <style> for theming and strips event handlers, CDATA, PI, javascript:/data:text/html hrefs — verify these semantics match your CSP.
• Version coupling — v3 requires PHP 8.4 + Symfony 7.4; 2.x supports PHP 8.2 / Symfony ^6.4. Pulling Symfony 7.4 components into a Laravel 10/11 app can create dependency conflicts with Laravel's own symfony/* constraints. Resolve this in a spike before committing.
• Sub-tree repo signals are misleading — 56 stars and 0 dependents reflect a read-only split of the symfony/ux monorepo, not adoption. Real usage, issues, and PRs live upstream. Do not use these metrics in a build/buy scorecard; instead assess Symfony core-team backing and release cadence (steady, with prompt security backports to 2.x).
• Output instability — v2.24.0 added xmlns to downloaded icons, explicitly breaking tests that assert on ux_icon() output. Any snapshot/HTML-diff test suite must be attribute-order tolerant.
• Licensing of icon sets — Iconify aggregates third-party sets with mixed licenses (MIT/Apache-2.0 through CC-BY and share-alike). Remote fetching does not launder the license; legal review is required per set.

Key questions

• Is Twig already in the stack, or is this a Blade shop? (Decisive.)
• Which icon sets, and are their licenses cleared for our distribution model?
• Can we self-host and lock all icons, eliminating runtime Iconify calls entirely?
• Who owns the adapter, and will we upstream it or fork?
• What is the CSP posture, and does inline <svg> with <style> blocks comply?
• Is HTML payload weight acceptable where the same icon repeats dozens of times per page?

Integration Approach

Stack fit — Poor-native, moderate-with-work. Laravel's rendering path is Blade + Illuminate\View; this package's value is Twig-shaped. The realistic integration is a thin Laravel package we own (acme/laravel-icons) that depends on symfony/ux-icons internals and exposes idiomatic Blade ergonomics: <x-icon name="mdi:check" class="w-4 h-4" />, a @icon directive, and config/icons.php mirroring the upstream options (default_icon_set, icon_sets, aliases, iconify.auto_lock, ignore_not_found).

Migration path

1. Freeze the current state — inventory every icon in use (inline SVG, Font Awesome, sprite sheets) and map to prefix:name identifiers. This inventory is the migration backlog and the license-review list.
2. Land the adapter behind a feature flag; ship one screen (e.g., nav/sidebar) as a canary.
3. Lock icons — run the lock command in dev, commit the SVG directory, set iconify on-demand off in production. This converts a network dependency into a file read.
4. Backfill screen-by-screen; delete Font Awesome / sprite assets as each surface migrates.
5. Remove the flag and delete legacy icon loaders.

Compatibility

• Requires PHP 8.2+ (2.x) or 8.4+ (3.x); confirm against Laravel version support windows.
• Needs symfony/http-client for remote fetch (2.25.0 improved DX when absent) — irrelevant once icons are locked, so locking removes a whole dependency.
• Livewire/Inertia/Alpine interop is fine for static output, but note icons render server-side per request; with Inertia you must pass rendered markup as a prop or accept duplication. Livewire re-renders can multiply cost without the rendered-HTML cache warm.
• Blade component attributes (class, fill, aria-*) pass through cleanly; int/float attribute support (2.20.0) covers width/height/stroke-width.

Sequencing

1. Week 0 — security + legal gate: pin >=3.2.0, run composer audit, clear the icon cache post-upgrade so cached icons are re-sanitized, clear icon-set licenses.
2. Week 1 — spike: prove IconRenderer boots in a Laravel ServiceProvider with a PSR-6 adapter over CacheRepository; measure render cost for a 60-icon page. Kill criterion: unresolvable Symfony/Laravel dependency conflict → fall back to blade-ui-kit.
3. Week 2–3 — build adapter + Blade component + config + tests (attribute-order-tolerant snapshots; ignore_not_found: true in prod, false in CI so missing icons fail the build).
4. Week 3 — lock all icons, commit them, enable auto_lock in dev only, add icons:lock/icons:clear Artisan commands wrapping upstream.
5. Week 4 — canary screen, then rollout; add deploy-pipeline cache warmup step once the equivalent cache:warmup hook is wired to Laravel's optimize/artisan bootstrapping.
6. Post-rollout — retire Font Awesome license/CDN, update design-system docs with the icon identifier convention.

Operational Impact

Maintenance — Two maintenance surfaces: (a) upstream symfony/ux-icons, actively maintained by the Symfony core team with a clean security-backport record to 2.x; (b) our adapter, which is the real cost — it depends on non-public API shape and will break on minor releases. Budget ~1–2 engineer-days per upstream minor release for verification, more for majors (3.0 dropped PHP 8.3 support outright). Pin exact versions, upgrade deliberately, and keep an integration test suite as the upgrade gate. Note the repo is a read-only split: issues and PRs go to symfony/ux, so we cannot patch in place — we'd maintain a fork or upstream PRs.

Support — No vendor SLA (MIT, community). Internal support burden is "who understands Symfony DI and the sanitizer?" — realistically 1–2 named owners. Document the sanitizer's allowlist behavior for the security team, since it is the control preventing stored XSS from third-party SVG. Also document that clearing the icon cache is mandatory after any upgrade touching sanitization, or stale unsanitized output persists.

Scaling

• Server CPU — Good after 3.6.0: rendered-HTML cache, one cache fetch per icon per request, and local-icon warmup at deploy. Icon-dense pages (tables, nav) go from N renders to ~1.
• Network — Only at risk if on-demand remote fetching is left enabled. Disable it in production; then the only external dependency is the deploy-time lock step.
• Payload — The unaddressed axis. Inlining the same 24×24 SVG 40 times in a table adds real HTML weight with zero cache benefit per icon (only the page is cacheable). For icon-dense surfaces, prefer an SVG <symbol> sprite + <use>. Decide this at design-system level, not per feature.
• Cold start — Warmup covers local icons only; remote/on-demand icons still fetch on first request. Another reason to lock.

Failure modes

Ramp-up — Low for consumers, moderate for maintainers. A Blade developer needs ~30 minutes to learn <x-icon name="prefix:name" class="…" /> and the currentColor styling convention. The adapter owner needs working knowledge of Symfony DI, service tags, config trees, and PSR-6 cache contracts — 2–3 days of focused reading plus the spike. Designers/PMs need one artifact: the icon catalog (prefix:name → license → owner), which doubles as the migration checklist and the compliance record.

Recommendation — Approve a one-week spike only, gated on (a) dependency resolution in our Laravel version and (b) license clearance for the target icon sets. If the spike fails, adopt blade-ui-kit/blade-icons and port the sanitizer concept rather than the code. If it succeeds, adopt with locked icons, on-demand fetching disabled in production, and >=3.2.0 pinned, and scope the first release to a single canary surface before any Font Awesome retirement.