Famfamfam Flags Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require legacy-icons/famfamfam-flags
   

   Publish the CSS (if needed):

   php artisan vendor:publish --tag=famfamfam-flags
   

2. First Use Case Include the CSS in your resources/css/app.css:

   @import 'legacy-icons/famfamfam-flags/dist/css/famfamfam-flags.css';
   

   Use the flag icons in Blade:

   <span class="flag-icon flag-icon-us"></span> <!-- US Flag -->
   <span class="flag-icon flag-icon-gb"></span> <!-- UK Flag -->
   

3. Where to Look First

   • Documentation: Check the GitHub repo (if available) for icon classes.
   • CSS File: Inspect vendor/legacy-icons/famfamfam-flags/dist/css/famfamfam-flags.css for all available classes.
   • Demo: Use famfamfam’s original demo for visual reference.

Implementation Patterns

Common Workflows

1. Dynamic Flag Rendering Use a helper or Blade component to fetch flags dynamically:

   // app/Helpers/FlagHelper.php
   function renderFlag($countryCode) {
       return '<span class="flag-icon flag-icon-' . strtolower($countryCode) . '"></span>';
   }
   

   Blade usage:

   @renderFlag($user->country_code)
   

2. Integration with Laravel Collections Add a flag icon to a user collection:

   $users->each(function ($user) {
       $user->flag_icon = '<span class="flag-icon flag-icon-' . strtolower($user->country_code) . '"></span>';
   });
   

3. CSS Customization Override flag colors/sizes in your app.css:

   .flag-icon {
       width: 24px;
       height: 16px;
       background-color: #f00; /* Fallback */
   }
   

4. Localization + Flags Combine with Laravel’s localization:

   // config/app.php
   'locales' => ['en', 'fr', 'de'],
   

   Blade:

   @foreach(config('app.locales') as $locale)
       <span class="flag-icon flag-icon-{{ strtolower($locale) }}"></span>
   @endforeach
   

Integration Tips

• Tailwind CSS: Use arbitrary variants to style flags:

  <span class="flag-icon flag-icon-us w-6 h-4 text-red-500"></span>
  

• Laravel Mix: Ensure the CSS is processed:

  // webpack.mix.js
  mix.postCss('resources/css/app.css', 'public/css', [
      require('tailwindcss'),
  ]);
  

• Livewire/Alpine: Bind flags to dynamic data:

  <div x-data="{ country: 'us' }">
      <span class="flag-icon" :class="'flag-icon-' + country"></span>
  </div>
  

Gotchas and Tips

Pitfalls

1. Missing Country Codes

   • Not all countries have flags (e.g., flag-icon-xx may not exist).
   • Fix: Use a fallback or extend the package (see Extension Points).

2. CSS Specificity Conflicts

   • Custom styles may override the sprite.
   • Fix: Use !important sparingly or scope your CSS:

     .user-flags .flag-icon { ... }
     

3. Performance

   • The sprite adds ~5KB to your CSS.
   • Fix: Lazy-load flags or use inline SVGs for critical paths.

4. Responsiveness

   • Flags may not scale well on mobile.
   • Fix: Use max-width or media queries:

     @media (max-width: 768px) {
         .flag-icon { width: 18px; height: 12px; }
     }
     

Debugging

• Inspect Element: Check if the sprite URL is loaded (e.g., background-image: url(...)).
• Clear Cache: Run php artisan view:clear if flags disappear after updates.
• Fallback Colors: Add a gradient background for missing flags:

  .flag-icon:not([class*="flag-icon-"]):after {
      content: "?";
      background: linear-gradient(45deg, #ccc, #999);
  }
  

Config Quirks

• No Laravel Config: The package has no config/famfamfam-flags.php; all settings are CSS-based.
• Custom Paths: If publishing fails, manually copy the CSS to public/css/.

Extension Points

1. Add Missing Flags

   • Fork the repo, add SVG flags, and regenerate the sprite using this tool.
   • Alternative: Use flag-icon-css for more comprehensive flags.

2. SVG Fallback Replace the sprite with inline SVGs for better maintainability:

   <svg class="flag-icon" viewBox="0 0 64 48" aria-label="US">
       <path d="M0 0h64v48H0z" fill="#b22234"/>
       <path d="M0 0h64v15H0z" fill="#fff"/>
       <path d="M0 15h32v15H0z" fill="#3c3b6e"/>
   </svg>
   

3. Dynamic Sprite Loading Load the sprite only when needed (e.g., on pages with flags):

   @if(request()->routeIs('users.index'))
       <link rel="stylesheet" href="{{ asset('vendor/legacy-icons/famfamfam-flags/dist/css/famfamfam-flags.css') }}">
   @endif