Getting Started

Minimal Steps

Installation

composer require spatie/laravel-google-fonts
php artisan vendor:publish --provider="Spatie\GoogleFonts\GoogleFontsServiceProvider" --tag="google-fonts-config"

Publishes the config/google-fonts.php file with default settings.

Configure Fonts Add your Google Font embed URLs to the fonts array in config/google-fonts.php:

'fonts' => [
    'default' => 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
    'secondary' => 'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400&display=swap',
],

First Use Case Load fonts in a Blade view using the @googlefonts directive:

<head>
    @googlefonts  <!-- Loads 'default' font -->
    @googlefonts('secondary')  <!-- Loads 'secondary' font -->
</head>

Prefetch Fonts (Optional) Run the Artisan command to pre-download fonts for immediate availability:
```
php artisan google-fonts:fetch
```

Implementation Patterns

Core Workflows

Font Registration & Usage
- Register fonts in config/google-fonts.php with descriptive keys (e.g., default, code).
- Use @googlefonts('key') in Blade templates to load specific fonts.
- Default font loads automatically with @googlefonts (no argument).
Dynamic Font Loading
- Pass an array to @googlefonts for advanced options (e.g., CSP nonces):
```
@googlefonts(['font' => 'secondary', 'nonce' => csp_nonce()])
```
Prefetching Strategy
- Eager Loading: Run php artisan google-fonts:fetch during deployment to pre-download all fonts.
- Lazy Loading: Enable lazy mode (v1.6+) by modifying the GoogleFontsManager service provider to defer fetching until first request:
```
// In a service provider or config
$this->app->singleton(GoogleFontsManager::class, function ($app) {
    return new GoogleFontsManager($app['config'], $app['files'], $app['cache'], true); // true = lazy
});
```
Integration with CSP
- Use the nonce option to comply with Content Security Policy (CSP):
```
@googlefonts(['nonce' => csp_nonce()])
```

Multi-Environment Setup

Override font URLs per environment (e.g., config/google-fonts.php):

'fonts' => [
    env('APP_ENV') === 'production'
        ? 'production_url_here'
        : 'development_url_here',
],

Advanced Patterns

Custom Disk/Path Configuration
- Store fonts in a custom disk (e.g., S3) or path:
```
'disk' => 's3',
'path' => 'custom-fonts-path',
```
- Ensure the disk is linked or configured for public access.
Fallback Behavior
- Disable fallback to Google’s CDN in config/google-fonts.php:
```
'fallback' => false, // Throws exceptions on failure (debug mode only)
```
- Handle exceptions in a global exception handler or middleware.

Conditional Font Loading

Use Blade directives conditionally:

@if(auth()->check())
    @googlefonts('premium-font')
@endif

Local Development Optimization
- Disable inlining for faster development iteration:
```
'inline' => env('APP_ENV') === 'local' ? false : true,
```
Font Preloading
- Enable preload tags for critical fonts:
```
'preload' => true,
```
- Preload tags are automatically generated for fonts with preload: true.

Gotchas and Tips

Pitfalls

Storage Link Requirement
- Issue: Fonts fail to load with 404 errors.
- Fix: Run php artisan storage:link to symlink storage/app/public to public/storage.
- Note: If using a custom disk/path, ensure the directory is accessible via HTTP.
User Agent Limitations
- Issue: Legacy browsers (e.g., IE) may not support WOFF2 fonts.
- Fix: Override the user_agent in config to target older formats:
```
'user_agent' => 'Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)',
```
- Tradeoff: Increases payload size for modern browsers.
Caching Quirks
- Issue: Changes to font URLs/config aren’t reflected immediately.
- Fix: Clear the cache:
```
php artisan cache:clear
php artisan view:clear
```
- Tip: Use php artisan google-fonts:fetch --force to re-fetch fonts.
Duplicate Font URLs
- Issue: Multiple entries with the same URL may cause conflicts.
- Fix: The package deduplicates URLs internally, but ensure config entries are unique.
Nonce Mismatches
- Issue: CSP blocks font loading despite correct nonce usage.
- Fix: Verify the nonce matches the CSP directive:
```
@googlefonts(['nonce' => csp_nonce()])
```
```
// In CSP middleware
$directive->addStyleSources(['nonce' => csp_nonce()]);
```
Git Ignore Conflicts
- Issue: storage/app/public/fonts is ignored by .gitignore.
- Fix: Exclude the directory from .gitignore if you want to version-control fonts:
```
!/storage/app/public/fonts/
```

Debugging Tips

Check Fetch Logs
- Enable debug mode to log fetch operations:
```
'fallback' => true, // Logs errors to Laravel logs
```
- Inspect logs at storage/logs/laravel.log.
Verify Font Files
- Manually check if fonts exist in storage/app/public/fonts after running google-fonts:fetch.
- Use php artisan storage:link if files are missing in public/storage/fonts.

Test Fallback Behavior

Temporarily disable the package to test fallback:

// In AppServiceProvider
$this->app->bind(GoogleFontsManager::class, function () {
    return new class {
        public function render($font = null) { return '<link href="https://fonts.googleapis.com/..." rel="stylesheet">'; }
    };
});

Inspect Blade Output

Use @dd to debug the directive’s output:

@googlefonts(['font' => 'test'])
@dd($__env->yieldContent('googlefonts'))

Extension Points

Custom Fetch Logic
- Override the GoogleFontsManager to implement custom fetching (e.g., proxy requests):
```
$manager->setFontFetcher(new CustomFontFetcher());
```

Dynamic Font Registration

$config = config('google-fonts.fonts');
$config['dynamic-font'] = 'https://fonts.googleapis.com/...';
config(['google-fonts.fonts' => $config]);

Post-Fetch Processing

Extend the FontFetcher to modify downloaded files (e.g., optimize WOFF2):

use Spatie\GoogleFonts\FontFetcher;

class CustomFontFetcher extends FontFetcher {
    protected function processFontFile($contents, $url) {
        // Custom logic (e.g., compression)
        return parent::processFontFile($contents, $url);
    }
}

Event Listeners

Listen for font fetch events to log or analyze usage:

use Spatie\GoogleFonts\Events\FontsFetched;

FontsFetched::listen(function (FontsFetched $event) {
    Log::info('Fetched fonts:', $event->fonts);
});

Conditional Inlining
- Dynamically toggle inlining based on request context (e.g., mobile devices):
```
'inline' => function () {
    return !request()->isMobile();
},
```

Laravel Google Fonts Laravel Package