Font Manager Laravel Package

Getting Started

• Install with composer require symfinity/font-manager, then publish the package assets: php artisan vendor:publish --provider="Symfinity\FontManager\FontManagerServiceProvider". This gives you config/font-manager.php plus any publishable CSS/stub views — read the config file first, it is the real documentation for this package.
• Look at three things before writing code: config/font-manager.php (font sets, sources, storage disk, cache TTL), the package README on GitHub (usage examples track the release tag, so browse the v0.2.6 tree rather than main), and CHANGELOG.md — the v0.2.6 notes are a one-line bugfix pointer, so the changelog is the only place to see what actually changed between 0.2.5 and 0.2.6.
• Confirm where fonts are stored. Most setups use a Laravel disk (storage/app/public/fonts or a fonts entry in config/filesystems.php) and expose them via php artisan storage:link. If the CSS is generated with absolute URLs, set APP_URL correctly before your first render or you will bake the wrong host into cached stylesheets.
• First use case: replace a Google Fonts <link> in your layout with self-hosted fonts. Define the family in the config, run the package's download/sync command (check php artisan list for the font namespace), reference the generated stylesheet in your Blade layout, and verify with the Network tab that requests now hit your own domain. That single change covers the two most common motivations for adopting this package: GDPR/third-party-request removal and control over font loading performance.

Implementation Patterns

• Config-as-source-of-truth. Declare families, weights, styles and subsets in config/font-manager.php and treat that file as the contract. Keep environment-specific values (disk, CDN base URL, cache store) in .env and reference them from the config with env(), so staging and production can point at different storage without code changes.
• Build-time vs. runtime generation. For anything static, generate the CSS in a deploy step or a small custom Artisan command and commit/copy the output, rather than resolving fonts on every request. Runtime generation is fine for multi-tenant or per-user font selections, but only behind a cache.
• Blade integration. Wrap the stylesheet output in a single partial (resources/views/partials/fonts.blade.php) that emits both the <link rel="preload"> tags for your critical weights and the @font-face stylesheet. Including it from your base layout keeps font loading in one place instead of scattered across layouts.
• Vite/asset pipeline coexistence. If you already use Vite, either let the package own font CSS entirely or import the generated stylesheet into your app.css. Don't do both — duplicate @font-face blocks with different src paths are the most common cause of "the font loads but the wrong weight shows".
• Deployment workflow. Put the font sync/download command in your deploy script after storage:link and before config:cache, and make it idempotent so repeated deploys don't re-download unchanged files. Follow it with a cache clear for the package's cache store.
• Testing. In tests, point the package at a local/null disk and a array cache driver, and avoid commands that hit the network. If you assert on rendered HTML, assert on the presence of @font-face and the preload tag rather than exact URLs, which vary by APP_URL.
• Multi-tenant / dynamic fonts. Register or resolve font sets per tenant at runtime and key the cache by tenant identifier. This is the one scenario where you should not rely purely on the static config file.

Gotchas and Tips

• 0.x versioning. At 0.2.6 the package is pre-1.0, so minor bumps may still change config keys, method signatures or generated CSS structure. Pin to ^0.2.6 in composer.json and read CHANGELOG.md on every update — the release notes themselves are terse and will not warn you about config changes.
• Stale cached CSS. After editing config/font-manager.php, config caching (php artisan config:cache) means your changes are invisible until you re-cache. Symptom: "I changed the weight and nothing happened." Always config:clear in local dev.
• Missing files after deploy. Font binaries usually live outside version control. A fresh clone will render @font-face rules pointing at 404s. Guard against this with a deploy check, or set font-display: swap so a failure degrades to the fallback stack instead of invisible text.
• CLS from late discovery. Generated CSS alone does not fix layout shift. Pair the stylesheet with <link rel="preload" as="font" type="font/woff2" crossorigin> for the one or two weights used above the fold, and set explicit font-family fallbacks with size-adjust where the metrics differ noticeably.
• Network access during builds. Any command that fetches upstream fonts will fail in a network-restricted CI container or an air-gapped host. Provide a committed font directory and a flag/config to skip downloads, or run sync only in environments that legitimately have egress.
• Disk and URL mismatch. Writing to a private disk while generating public URLs (or vice versa) produces correct-looking CSS with broken sources. Verify filesystems.disks.<your-disk>.url matches the disk the package writes to.
• Extension points worth knowing. The generated stylesheet is normally publishable — override the package view/CSS stub rather than string-replacing output. If you need custom unicode-range or variable-font font-variation-settings, do it in the published stub; that survives package upgrades, whereas monkey-patching the facade does not.
• Debugging order when a font doesn't render: (1) does the URL in the generated CSS return 200 in a browser, (2) is the family name in the CSS byte-identical to the one in your font-family declaration (quotes and casing matter), (3) is the weight you requested actually in the set, (4) is a stale cached stylesheet being served.
• v0.2.6 specifically. This is a bugfix release with no new features or documented breaking changes, so upgrading from 0.2.x should be low risk — but check the changelog for which bug was fixed, since a rendering or path bug in 0.2.5 may mean you have a workaround in your code (custom CSS overrides, manual @font-face blocks) that should be removed now.