Ux Fontawesome Laravel Package

Getting Started

krystal-sf/ux-fontawesome is a thin icon-set provider: it vendors Font Awesome Free assets and registers them with Symfony UX Icons (symfony/ux-icons), so you render icons through the standard ux_icon() Twig function instead of hand-writing <i class="fa-solid fa-...">. It targets Symfony 6.4/7.x projects in the Krystal estate. There is no Laravel service provider, no Blade component, and no Vite integration — a Laravel developer's day-to-day leverage with this package is either (a) working inside a Symfony service, or (b) using it as a reference implementation for your own Blade icon component.

Install (Symfony context):

composer require krystal-sf/ux-fontawesome
php bin/console cache:clear

There is almost certainly no Flex recipe, so expect manual wiring: register the bundle in config/bundles.php if one ships, and create config/packages/ux_fontawesome.yaml for whatever config tree src/DependencyInjection/Configuration.php defines.

Read in this order before writing templates:

First use case — verify the prefix, then render one icon. The prefix is the single thing that must be confirmed before you commit icon names to templates (fa, fontawesome, fas/far/fab per style are all plausible):

grep -rn "getPrefix\|function getName\|IconSet" vendor/krystal-sf/ux-fontawesome/src

Then prove it with a throwaway template:

{# templates/_smoke.html.twig #}
<button class="btn btn-primary">
    {{ ux_icon('fa:user', {class: 'w-4 h-4 me-1'}) }}
    Edit profile
</button>

If the prefix is wrong you get an IconNotFoundException at render time, so do this before batching icon markup across a dozen templates.

Laravel equivalent for the same first use case (since the package won't run there):

npm i -D @fortawesome/fontawesome-free

// app/View/Components/Icon.php
public function render() { return view('components.icon'); }

{{-- resources/views/components/icon.blade.php --}}
<svg class="w-4 h-4 {{ $class ?? '' }}" aria-hidden="true"><use href="#fa-{{ $name }}"/></svg>

Implementation Patterns

Treat ux_icon() as the only call site. The package's job is to feed a set name into Symfony UX Icons; your job is to never scatter raw fa-* class strings. Use the attributes array as the styling hook and let currentColor inherit from the parent:

<span class="text-danger">
    {{ ux_icon('fa:triangle-exclamation', {class: 'w-5 h-5'}) }}
</span>

Wrap it once behind a project macro. Given zero stars, zero dependents and single-org provenance, the highest-value pattern is an abstraction that makes the package swappable in one edit — to Iconify, local SVGs, or Heroicons:

{# templates/_icon.html.twig #}
{% macro icon(name, attrs = {}) %}
    {{ ux_icon('fa:' ~ name, attrs|merge({class: 'icon ' ~ (attrs.class ?? '')})) }}
{% endmacro %}

{% import '_icon.html.twig' as ui %}
{{ ui.icon('user', {class: 'w-4 h-4'}) }}

Keep a named icon catalogue. Centralize the semantic → Font Awesome mapping so a FA major bump is a single-file diff:

{# templates/_icons.html.twig — or a Twig constant map in a service #}
{% set ICONS = {
    'edit': 'pen',
    'delete': 'trash-can',
    'warning': 'triangle-exclamation'
} %}

Pick an asset strategy deliberately. The package's position is "vendored assets compiled into the app." Confirm whether it supports AssetMapper (Symfony's default since 6.4) or only Webpack Encore — the two are not interchangeable, and an Encore-only package in an AssetMapper app means you copy the CSS yourself:

php bin/console debug:asset-map | grep -i fontawesome
php bin/console importmap:require @fortawesome/fontawesome-free  # AssetMapper path

Laravel teams: borrow the shape, not the dependency. Reproduce the same three properties — vendored assets, a prefix convention, and one wrapper component — with npm + Vite + a Blade component, or adopt blade-ui-kit/blade-icons if you want a maintained set. Do not composer require this into a Laravel app expecting it to work; there is no package discovery, container, or Twig runtime for it.

Cache and CI. Compile icons at build time (php bin/console cache:warmup in deploy) and add a smoke test that renders every name in your catalogue, so a bad rename fails CI rather than production 500s.

Gotchas and Tips

• Prefix mismatch is the #1 failure. IconNotFoundException on every page means you guessed fa: when the set exposes something else. Verify the prefix from source, not from a blog post, and only then bulk-edit templates.
• No Flex recipe. Anything a recipe would have done — bundle registration, YAML config, .env defaults — you do by hand. Diff a working install against a fresh one if icons silently don't register.
• Zero stars means you are the maintainer. Zero stars, zero dependents, single-org provenance, score 0. Assume no issue history to read, no community triage, and no promised upgrade path. Get a named owner and a fork strategy before this lands in composer.json.
• FA Free only. Pro icons (fa-pro:*, light/thin/duotone styles) are not included and would violate the license if bolted on. If your design calls for FA Pro, this is the wrong package.
• License obligations flow through. FA Free icons are CC BY 4.0, fonts SIL OFL 1.1, code MIT. Preserve attribution headers; audit them before shipping.
• Asset pipeline mismatch. Encore vs AssetMapper is a hard fork in the road. Verify by looking at what the package actually publishes (Resources/public/, importmap entries, or CSS only) rather than trusting the description's "autoconfiguration" claim.
• Production caching. Icons are resolved at render, and Symfony caches aggressively. cache:clear after any config or set change, or you'll debug a change that's already correct in source.
• Wrong icon names fail loudly at runtime — but only on the pages that render them. That means staging looks fine while a rarely-visited admin page 500s. The catalogue + CI smoke test pattern above is the fix.
• Self-hosting is a feature, not a detail. Vendoring avoids third-party CDN calls, which is the GDPR/offline checkbox that makes this defensible over a <link> to cdnjs. If you don't need that, a two-line import '@fortawesome/fontawesome-free/css/all.min.css' is a lower-maintenance answer.
• Don't standardize on it across a mixed PHP estate. Scope it to Symfony services with matching UX versions; Laravel services should use a Blade component over the npm package. A shared internal icon convention is worth centralizing — this package is not.
• Escape hatch first. If the wrapper macro/blade component exists on day one, replacing this package later is a one-file change. If it doesn't, you have coupled product templates to an unvetted dependency.