Getting Started

Minimal Setup

Installation:

composer require spatie/laravel-google-fonts

Publish the config file:

php artisan vendor:publish --provider="Spatie\GoogleFonts\GoogleFontsServiceProvider" --tag="google-fonts-config"

Configure Fonts: Edit config/google-fonts.php and define your fonts under the fonts key:

'fonts' => [
    'default' => 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
    'mono' => 'https://fonts.googleapis.com/css2?family=Fira+Code&display=swap',
],

First Use Case: Add the @googlefonts directive to your Blade layout (e.g., resources/views/layouts/app.blade.php):

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

Verify: Run php artisan google-fonts:download to pre-download fonts (optional but recommended for production). Clear cache if needed:
```
php artisan cache:clear
php artisan view:clear
```

Implementation Patterns

Core Workflow

Font Registration:
- Define fonts in config/google-fonts.php with their Google Fonts embed URLs.
- Use named keys (e.g., 'default', 'code') for easy Blade references.

Blade Integration:

Use @googlefonts for the default font.
Specify a named font with @googlefonts('font-name').

Example:

<body class="font-sans">
    @googlefonts('sans')  <!-- Loads 'sans' font -->
    <h1 class="font-mono">Code Example</h1>
    @googlefonts('mono')   <!-- Loads 'mono' font -->
</body>

Dynamic Font Loading:
- Pass dynamic font names via variables:
```
@googlefonts($dynamicFontName)
```
- Ensure the font is defined in the config or handle missing fonts gracefully (see "Gotchas").
Asset Organization:
- Fonts are stored in storage/app/public/google-fonts by default.
- Symlink the directory to public/google-fonts for web access:
```
php artisan storage:link --force
```
Caching:
- The package caches downloaded fonts and CSS. Clear caches when updating fonts:
```
php artisan google-fonts:clear-cache
```

Queueing Downloads:

For large-scale apps, defer downloads to a queue job:

// In a controller or command
\Spatie\GoogleFonts\GoogleFonts::downloadFont('font-name');

Publish the queue config if needed:

php artisan vendor:publish --provider="Spatie\GoogleFonts\GoogleFontsServiceProvider" --tag="google-fonts-queue"

Advanced Patterns

Conditional Loading:

Load fonts only on specific routes or views:

@if(Request::is('dashboard*'))
    @googlefonts('dashboard')
@endif

Font Stacks:
- Combine multiple fonts in a single directive by extending the Blade component:
```
@component('google-fonts', ['fonts' => ['sans', 'mono']])
@endcomponent
```
- Requires custom Blade component setup (see "Extension Points").
Local Overrides:
- Override the storage path in config/google-fonts.php:
```
'storage_path' => storage_path('app/custom-fonts'),
```

Custom CSS Processing:

Extend the CSS parser to modify font URLs or add custom properties:

// app/Providers/GoogleFontsServiceProvider.php
GoogleFonts::macro('customCss', function ($css) {
    return str_replace('original-url', 'custom-url', $css);
});

Testing:

Mock font downloads in tests:

$this->mock(\Spatie\GoogleFonts\GoogleFonts::class)
    ->shouldReceive('downloadFont')
    ->once();

Gotchas and Tips

Common Pitfalls

Missing Fonts:
- Issue: @googlefonts('undefined-font') throws an error.
- Fix: Define the font in config/google-fonts.php or wrap in a check:
```
@if(config('google-fonts.fonts.custom??'))
    @googlefonts('custom')
@endif
```
Caching Issues:
- Issue: Fonts don’t load after config updates.
- Fix: Clear caches explicitly:
```
php artisan google-fonts:clear-cache
php artisan view:clear
```
Storage Permissions:
- Issue: Fonts fail to download with "Permission denied" errors.
- Fix: Ensure storage/app/public is writable:
```
chmod -R 755 storage/app/public
```
Queue Failures:
- Issue: Font downloads hang or fail silently.
- Fix: Check queue workers and logs:
```
php artisan queue:work --verbose
```
- Monitor failed jobs in .env:
```
QUEUE_CONNECTION=database
```
CSS Injection Risks:
- Issue: Malicious CSS in Google Fonts embed URLs could inject scripts.
- Fix: Validate URLs in config/google-fonts.php and use allowlists.
Font Subsetting:
- Issue: Downloaded fonts include unused characters/glyphs.
- Fix: Use Google Fonts subsetting in the embed URL:
```
'fonts' => [
    'subset' => 'https://fonts.googleapis.com/css2?family=Inter&subset=latin-ext&display=swap',
],
```

Debugging Tips

Log Font Downloads:
- Enable debug mode in config/google-fonts.php:
```
'debug' => env('GOOGLE_FONTS_DEBUG', false),
```
- Check logs in storage/logs/laravel.log for download errors.
Verify Downloaded Files:
- Inspect storage/app/public/google-fonts for missing or corrupted files.
- Manually trigger a download:
```
php artisan google-fonts:download --font=font-name
```
Network Requests:
- Use browser dev tools to check if the local font CSS is loaded (should be inline in <head>).
- Ensure no 404s for font files (e.g., google-fonts/Inter.woff2).
Blade Directive Errors:
- Wrap directives in @if blocks to debug:
```
@if(false)
    @googlefonts('problematic-font')
@endif
```

Extension Points

Custom Blade Directives:

Extend the @googlefonts directive in AppServiceProvider:

Blade::directive('googlefonts', function ($expression) {
    return "<?php echo \\Spatie\\GoogleFonts\\GoogleFonts::render($expression); ?>";
});

Font Processing Hooks:

Override the CSS parser or asset downloader:

// app/Providers/GoogleFontsServiceProvider.php
$this->app->bind(\Spatie\GoogleFonts\CssParser::class, function () {
    return new CustomCssParser();
});

Asset Storage:

Replace the default storage handler:

// config/google-fonts.php
'storage_handler' => \App\Services\CustomFontStorage::class,

Queue Observers:

Add observers to the GoogleFontDownloaded event:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \Spatie\GoogleFonts\Events\GoogleFontDownloaded::class => [
        \App\Listeners\LogFontDownload::class,
    ],
];

Local Font Fallbacks:

Combine self-hosted Google Fonts with local fallbacks:

/* In your CSS */
body {
    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

Configuration Quirks

Environment-Specific Fonts:

Use environment variables to switch fonts:

'fonts' => [
    'default' => env('GOOGLE_FONT_DEFAULT', 'https://fonts.googleapis.com/css2?family=Inter&display=swap'),
],

Dynamic Config Loading:
- Load fonts from a database or API:
```
// In
```

Laravel Google Fonts Laravel Package