Famfamfam Flags Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require legacy-icons/famfamfam-flags
   

   Publish assets to public/vendor/flags (default location):

   php artisan vendor:publish --provider="LegacyIcons\FamfamfamFlags\FamfamfamFlagsServiceProvider" --tag="public"
   

2. Basic Usage Include the CSS in your layout:

   <link rel="stylesheet" href="{{ asset('vendor/flags/css/famfamfam-flags.css') }}">
   

   Use a flag in your Blade template:

   <div class="famfamfam-flags fr"></div>
   <!-- Renders the French flag -->
   

3. Direct Image Usage Reference individual flag images:

   <img src="{{ asset('vendor/flags/png/us.png') }}" alt="US Flag" width="16" height="11">
   

First Use Case: Country Selector

<select>
   @foreach (['us', 'fr', 'de', 'jp'] as $country)
      <option value="{{ $country }}">
         <span class="famfamfam-flags {{ $country }}"></span> {{ ucfirst($country) }}
      </option>
   @endforeach
</select>

Implementation Patterns

1. Asset Organization

• Default Structure:

  public/vendor/flags/
  ├── css/
  │   └── famfamfam-flags.css
  ├── png/
  │   ├── *.png (all flags)
  ├── gif/
  │   ├── *.gif (all flags)
  └── sprite/
      └── famfamfam-flags.png (spritesheet)
  

• Custom Paths: Override via config/flags.php:

  'path' => 'custom/path/to/flags',
  

2. Dynamic Flag Rendering

Use a Blade component or helper:

// app/Helpers/FlagHelper.php
function flag($code, $size = 'small') {
    return "<div class='famfamfam-flags {$code} {$size}'></div>";
}

Usage:

{{ flag('gb', 'large') }}

3. Spritesheet Optimization

• Lazy Loading: Load spritesheet only on pages needing flags.
• Critical CSS: Inline flag-related CSS for above-the-fold content.

4. Integration with Laravel Mix

Add to webpack.mix.js:

mix.copy('node_modules/famfamfam-flags/dist', 'public/vendor/flags');

5. Localization

Pair with Laravel’s localization:

// config/app.php
'flags' => [
    'us' => 'United States',
    'fr' => 'France',
],

Render:

<div class="famfamfam-flags {{ app()->getLocale() }}"></div>

Gotchas and Tips

Pitfalls

1. Missing ImageMagick

   • Error: Spritesheet generation fails during gulp build.
   • Fix: Install ImageMagick (brew install imagemagick on macOS) or skip spritesheet generation.

2. Caching Issues

   • Problem: Flags not updating after asset publish.
   • Fix: Clear Laravel cache and browser cache:

     php artisan cache:clear
     php artisan view:clear
     

3. Alias Confusion

   • Gotcha: RE (Réunion) aliases to FR but may not render if CSS isn’t updated.
   • Fix: Verify aliases.json and rebuild spritesheet if needed.

4. Path Configuration

   • Error: File not found for flags.
   • Debug: Check config/flags.php and verify public directory permissions.

Debugging Tips

1. Inspect CSS Use browser dev tools to confirm classes like .famfamfam-flags.fr exist in the generated CSS.

2. Verify File Existence Check public/vendor/flags/png/ for the correct flag files (e.g., fr.png).

3. Spritesheet Debugging

   • Open public/vendor/flags/sprite/famfamfam-flags.png in an image editor to verify flag placement.
   • Use Chrome DevTools to inspect the sprite’s background-position for a flag.

Extension Points

1. Custom Flags

   • Add new flags to resources/flags/png/ and update aliases.json.
   • Rebuild with:

     npm install -g gulp-cli
     gulp build
     

2. Dynamic Flag Loading Use JavaScript to load flags on demand:

   // Load flags only when needed
   if (document.querySelector('.famfamfam-flags')) {
       loadScript('/vendor/flags/js/flags-loader.js');
   }
   

3. Dark Mode Support Override CSS for dark themes:

   .dark-mode .famfamfam-flags {
       filter: invert(1);
   }
   

4. Accessibility Add ARIA labels:

   <div class="famfamfam-flags fr" role="img" aria-label="France"></div>
   

Performance Tips

• Inline Critical Flags: Use Laravel’s @stack to inline essential flags.
• Sprite Fallback: Provide individual flag images as fallback for older browsers.
• Lazy-Split CSS: Use Laravel Mix to split famfamfam-flags.css into smaller files per region.