Google Fonts Laravel Package

Getting Started

• Install with Composer and check the package README for Laravel-specific registration. The release notes reference Symfony Flex and AssetMapper, so in Laravel you will likely need to manually register the service provider and console commands.
• Publish or create the package config. The new release moves environment-specific behavior to YAML when@prod / when@dev; in Laravel, map those values to config/*.php and .env instead.
• Start with gfonts:status to confirm configuration, cache settings, and locked fonts. This is the quickest way to verify the package is wired correctly.
• First real use case: call google_fonts() in your Blade layout for a critical font, using the new text subset parameter and preload flag:

  google_fonts('Inter', text: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789', preload: true)
  

• Before locking fonts in a deploy pipeline, run gfonts:lock --dry-run and inspect the new CLI tables showing requested vs downloaded weights.
• Use gfonts:import --dry-run if you are importing local or catalog fonts, then run without --dry-run once the plan looks correct.

Implementation Patterns

• Subset aggressively for above-the-fold content. Use the text parameter with only the characters needed for hero headings, navigation, or branding. For body text with dynamic content, either use a broader subset or accept the full font file.
• Preload only the primary font. Set preload: true for the one or two fonts used in the initial viewport. Preloading many fonts delays other critical assets.
• Cache Google Fonts API responses. The default 1-hour TTL is sensible for production. In local development, lower the TTL or clear the cache when changing font families or weights.
• Lock fonts in CI/deploy. Run gfonts:lock --dry-run in pull requests and gfonts:lock during deployment. Commit the resulting manifest and font files if your deployment does not persist generated assets.
• Prune unused fonts after manifest changes. Run gfonts:status, then gfonts:prune --dry-run, then gfonts:prune. This keeps the locked fonts directory from growing stale.
• Use progress bars and tables for long CLI runs locally, but use --no-interaction and quiet output in CI. The new progress bars and detailed tables are helpful interactively; scripts should avoid ANSI noise.
• Adapt AssetMapper assumptions for Laravel. The release fixes AssetMapper paths to assets/ and uses relative ./font.woff2 URLs. In Laravel with Vite, you will likely need to adjust CSS url() paths or copy fonts into public/ and reference them with asset().
• Follow the integration tests as usage examples. The new release adds comprehensive workflow tests from template scanning to rendering; these are a good reference for expected manifest structure and command sequencing.
• Treat the manifest as the source of truth. The manifest now records only actually downloaded weights. Use it to drive CSS generation and pruning rather than re-requesting weights from Google Fonts.

Gotchas and Tips

• This package is Symfony-oriented. Symfony Flex recipes and AssetMapper are first-class; Laravel integration is not described in the release notes. Expect to write a small adapter for config, command registration, and asset paths.
• Requested weights are not guaranteed. The manifest records downloaded weights only, and CLI output now warns when weights are unavailable. Do not assume every requested weight exists; check the command tables.
• Subsetting can break dynamic content. If user-generated content includes characters outside your text subset, those glyphs may fall back or render incorrectly. Use subsetting only for known static text, or generate multiple subsets.
• Preload hints are easy to overuse. Preloading a font that is not used above the fold competes with CSS, JS, and images. Audit with Lighthouse after enabling preload.
• Clear the API cache when changing fonts or credentials. The new API response cache can serve stale Google Fonts metadata for up to an hour. In development, use a short TTL or clear the cache manually.
• Use dry-run before destructive commands. gfonts:prune removes fonts from the locked directory. If the manifest is stale, pruning can delete fonts still referenced by templates. Run gfonts:status and --dry-run first.
• Do not rely on Symfony YAML blocks in Laravel. when@prod and when@dev are Symfony container features. In Laravel, use environment-specific config files or env() checks cached via config:cache.
• Exception classes are final. You cannot extend package exceptions. If you need custom error handling, catch and wrap them rather than subclassing.
• File reading fallback matters on older stacks. The package uses Symfony 7.1+ Filesystem::readFile() when available and falls back to file_get_contents(). Ensure allow_url_fopen is enabled if remote reads go through the fallback, and check error handling if you run on older Symfony components.
• Watch for multiple manifests in tests. The release keys manifest caches by file path to avoid collisions. If you write your own tests, avoid sharing a single cache key across different manifest fixtures.
• Static analysis is strict. The package maintains PHPStan Level 9 and resolved Psalm errors. If you extend or wrap it, keep strict null checks and avoid truthy/falsy comparisons that the package now rejects.