PHPackages unloc/laravel-fontawesome-ondemand - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. unloc/laravel-fontawesome-ondemand ActiveLibrary unloc/laravel-fontawesome-ondemand ================================== Fetch Font Awesome icons on demand from the GraphQL API and cache them to disk. 083↓66.7%PHP Since Aug 5Pushed 3w agoCompare [ Source](https://github.com/unlocnl/laravel-fontawesome-ondemand)[ Packagist](https://packagist.org/packages/unloc/laravel-fontawesome-ondemand)[ RSS](/packages/unloc-laravel-fontawesome-ondemand/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependenciesVersions (1)Used By (0) Font Awesome On-Demand for Laravel ================================== [](#font-awesome-on-demand-for-laravel) Fetches Font Awesome 6 and 7 icons on demand from the official Font Awesome GraphQL API, caches them disk-first, and renders them through a `` Blade component. > **An API token is required.** The Font Awesome GraphQL `svgs` field is authenticated even for free icons, so an `FONTAWESOME_API_TOKEN` must be set to fetch any SVG markup — without one, every icon falls back to `on_error`. A free-tier token covers the free icon set; a Pro token additionally unlocks Pro families and styles. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11, 12, or 13 Installation ------------ [](#installation) ``` composer require unloc/laravel-fontawesome-ondemand php artisan vendor:publish --tag=fontawesome-config ``` This publishes `config/fontawesome.php`. Configuration ------------- [](#configuration) All keys live in `config/fontawesome.php`. KeyDescription`version`Font Awesome release series to query, `6` or `7`. Used verbatim in the GraphQL `release(version: "{version}.x")` query.`api_token`Reads `FONTAWESOME_API_TOKEN`. Required to fetch any SVG — the GraphQL `svgs` field is authenticated even for free icons. The client exchanges it for a short-lived GraphQL token and caches that exchange. A free-tier token covers free icons; a Pro token adds Pro families/styles.`endpoint`Font Awesome GraphQL endpoint. Override for testing/mocking.`defaults.family`Default family (`classic`, `sharp`, `sharp-duotone`, `duotone`) applied when ``'s `family` attribute is omitted. Note: `brands` is a *style*, not a family.`defaults.style`Default style (`solid`, `regular`, `light`, `thin`, `semibold`, `duotone`, `brands`) applied when ``'s `variant` attribute is omitted.`classes`CSS classes merged into every rendered `` by default (e.g. sizing utility classes). Component/attribute classes are appended, not replaced.`prefetch`List of icons to always warm via `fontawesome:prefetch`. Each entry is a string (icon name, uses defaults) or an array `['name' => ..., 'family' => ..., 'style' => ...]`.`scan_paths`Extra directories (beyond `resource_path('views')`) that `fontawesome:prefetch` scans for `` usages.`disk`Filesystem disk (from `config/filesystems.php`) used for the on-disk SVG cache.`path`Root path within that disk where cached SVGs are stored.`sanitize.strip_comments`Strip HTML/XML comments from fetched SVG markup before caching/rendering.`sanitize.remove_attributes`List of attribute names to strip from the SVG markup wherever they appear, not just the root `` element (e.g. inline `style`). Supports wildcards like `data-*`.`cache.store`Cache store name for the persistent (non-disk) icon cache. `null` uses the app's default cache store (persistent + negative caching on); `false` disables the persistent cache; a string uses that specific store.`cache.ttl`TTL in seconds for successfully resolved icons in the persistent cache. `null` caches forever.`cache.negative_ttl`TTL in seconds for negative (icon-not-found) cache entries, so failed lookups aren't retried on every request.`cache.prefix`Key prefix used for all persistent cache entries, to avoid collisions with other cached data.`on_error`Behavior when an icon can't be resolved: `placeholder` (render a fallback SVG), `throw` (throw `IconNotFoundException`), or `empty` (render nothing).`blaze.fold`Register `` with Livewire Blaze for compile-time folding. Defaults to `true` and is ignored when Blaze isn't installed. See [Livewire Blaze](#livewire-blaze).Usage ----- [](#usage) ### Blade component [](#blade-component) ``` {{-- brand auto-resolved --}} ``` `name` is required; `family` and `variant` fall back to `defaults.family`/`defaults.style` when omitted. Any other attributes (including `class` and `style`) are merged onto the rendered `` root element — default classes, existing SVG classes, and attribute classes are combined and deduplicated. Brand icons (`github`, `square-github`, `gitlab`, `google`, `php`, `laravel`, ...) are recognized from the complete bundled brand list in `resources/brands.php` — all Font Awesome brand names, including the `square-*` variants — and resolved directly against the classic family with the `brands` style (`classic`/`brands`) in a single query, without needing to pass a family or style. Any name not in the list (e.g. a brand added in a newer release) still resolves via an automatic `classic`/`brands` fallback — just with one extra request on first fetch. The list is a first-fetch optimization only. Regenerate it against the latest release with: ``` composer update-brands # 7.x by default composer update-brands -- 6.x # a specific release line ``` This pulls the current brand set from Font Awesome's public GraphQL metadata (no API token required). ### Facade [](#facade) ``` use Unloc\FontAwesome\Facades\FontAwesome; FontAwesome::render('gear'); // Illuminate\Support\HtmlString, ready to echo FontAwesome::get('gear'); // raw sanitized SVG markup, or null if not found ``` `render()` accepts `name`, `family`, `style` (the `` `variant` attribute maps to this parameter), plus an attributes array/`ComponentAttributeBag` for merging — it's what `` calls under the hood. `get()` returns the sanitized SVG string (or `null`) without attribute merging, useful for programmatic checks. ### Commands [](#commands) ``` php artisan fontawesome:prefetch php artisan fontawesome:clear php artisan fontawesome:clear --views ``` `fontawesome:prefetch` warms the cache for everything in `config('fontawesome.prefetch')` plus every static `` usage found by scanning `resource_path('views')` and any `scan_paths`. Usages with dynamic bindings (e.g. `:name="$icon"` or `{{ $var }}` interpolation) are skipped and counted, since the icon name can't be determined statically. `fontawesome:clear` deletes cached SVGs from disk and flushes the persistent icon cache (scoped to the configured prefix — it never calls `Cache::flush()`). It leaves compiled Blade views untouched; pass `--views` to also run `view:clear`, which is what you want when Blaze has folded icons into them (see below). Livewire Blaze -------------- [](#livewire-blaze) When [Livewire Blaze](https://github.com/livewire/blaze) is installed, this package registers `` for compile-time folding. A statically named usage compiles to the literal SVG in the parent template: ``` ``` ``` ``` No component render, no cache lookup, no disk read at runtime. Usages with a dynamically bound `name`, `family`, or `variant` (e.g. `:name="$icon"`) are left alone by Blaze and resolve at runtime as usual. Set `blaze.fold` to `false` to opt out. Because the registration targets the component file exactly, and exact-file matches always win in Blaze's path resolution, this config key — not `Blaze::optimize()->in(...)` on a parent directory — is how you turn it off. An icon that can't be resolved is never folded. During a fold the package ignores `on_error` and throws, so Blaze falls back to emitting the unfolded component and your configured `on_error` applies at runtime instead. A transient API failure at build time therefore costs you the optimisation for that icon, not a placeholder baked into the page. (If you've turned on Blaze's own throw mode with `Blaze::throw()`, it rethrows instead of falling back — which is what you want while debugging.) Run `fontawesome:prefetch` before `view:cache` so folding has a warm cache to read from. Without it, compilation still works, but it resolves icons over the network from inside the Blade compiler. Compiled views are invalidated by the mtime of the component file, so clearing the icon cache or changing `fontawesome.*` config does not refresh already-folded output. That is what `fontawesome:clear --views` is for. Notes ----- [](#notes) - `` is registered as an anonymous component, which is what makes Blaze folding possible. - Rendering happens server-side to plain SVG markup, so Inertia/Vue/React front ends can consume the output directly (e.g. via `v-html` or `dangerouslySetInnerHTML`) without a JS-side Font Awesome dependency. - Resolution order is: in-memory request cache → persistent cache (`cache.store`) → disk cache (`disk`/`path`) → GraphQL API. A successful API fetch is sanitized once and written back to both the disk cache and the persistent cache. License ------- [](#license) MIT. ### Health Score 22 — LowBetter than 21% of packages Maintenance62 Regular maintenance activity Popularity9 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/1ed9daf065d180c07266fb155fa37e2c2a567f43dde72d5138a8cb1b771a7c9a?d=identicon)[unlocdavid](/maintainers/unlocdavid) --- Top Contributors [![unlocdavid](https://avatars.githubusercontent.com/u/75703724?v=4)](https://github.com/unlocdavid "unlocdavid (3 commits)") ### Embed Badge ![Health badge](/badges/unloc-laravel-fontawesome-ondemand/health.svg) ``` [![Health](https://phpackages.com/badges/unloc-laravel-fontawesome-ondemand/health.svg)](https://phpackages.com/packages/unloc-laravel-fontawesome-ondemand) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)