Flag Icons Circle Laravel Package

## Getting Started

### Minimal Steps
1. **Install the Package**:
   ```bash
   composer require moox/flag-icons-circle

This automatically pulls in the required blade-ui-kit/blade-icons dependency.

2. Publish Assets (Optional): If you need to customize the SVG flags or paths:

   php artisan vendor:publish --provider="Moox\FlagIconsCircle\FlagIconsCircleServiceProvider" --tag="public"
   

   This copies the SVG assets to public/vendor/moox/flag-icons-circle.

3. First Usage: Use the Blade directive in your views:

   @flagIconsCircle('us')  <!-- Renders the US flag in a circle -->
   

   Or use the component syntax:

   <x-flag-icon country="gb" />
   

4. Verify Installation: Check if the flag renders correctly in your Blade template. Test with a few country codes (e.g., us, gb, jp).

Implementation Patterns

Usage Patterns

1. Static Flags: Use for fixed country representations (e.g., footer, about page):

   @flagIconsCircle('ca')  <!-- Canada -->
   

2. Dynamic Flags from Database: Fetch country codes from a model and render dynamically:

   @foreach($users as $user)
       @flagIconsCircle($user->country_code, ['alt' => $user->country_name])
   @endforeach
   

3. Integration with Forms: Use flags in dropdowns or selectors:

   <select>
       <option value="us">@flagIconsCircle('us') United States</option>
       <option value="de">@flagIconsCircle('de') Germany</option>
   </select>
   

4. Custom Attributes: Pass additional HTML attributes for styling or accessibility:

   @flagIconsCircle('fr', [
       'class' => 'w-10 h-10 border rounded-full',
       'aria-label' => 'France'
   ])
   

5. Livewire/Alpine Integration: Combine with Livewire for reactive country selection:

   <div x-data="{ country: 'us' }">
       @flagIconsCircle($country)
       <select x-model="country">
           <option value="us">United States</option>
           <option value="gb">United Kingdom</option>
       </select>
   </div>
   

Workflows

1. User Profiles: Display a user's country flag next to their name:

   <div class="flex items-center">
       @flagIconsCircle($user->country_code)
       <span>{{ $user->name }}</span>
   </div>
   

2. Country Selector Dropdown: Create a visually rich dropdown for multi-country support:

   <div class="relative">
       <button class="px-4 py-2">Select Country</button>
       <div class="absolute mt-2 w-48 bg-white rounded shadow">
           @foreach($countries as $country)
               <div class="px-4 py-2 hover:bg-gray-100 flex items-center">
                   @flagIconsCircle($country->code)
                   <span class="ml-2">{{ $country->name }}</span>
               </div>
           @endforeach
       </div>
   </div>
   

3. Geolocation Features: Use flags to represent regional data in dashboards:

   @foreach($regionalStats as $stat)
       <div class="flex items-center">
           @flagIconsCircle($stat->country_code)
           <div class="ml-2">
               <p>{{ $stat->country_name }}</p>
               <p>{{ $stat->value }}</p>
           </div>
       </div>
   @endforeach
   

Integration Tips

• Tailwind CSS: Use utility classes to control size and spacing:

  @flagIconsCircle('au', ['class' => 'w-6 h-6 mr-2'])
  

• Dark Mode: Add dark mode support via CSS:

  @flagIconsCircle('jp', ['class' => 'dark:invert'])
  

• Lazy Loading: For performance, lazy-load flags in long lists:

  @foreach($countries as $country)
      <div class="lazy-load">
          @flagIconsCircle($country->code)
      </div>
  @endforeach
  

  Use JavaScript to load flags only when they enter the viewport.

• Accessibility: Always include alt text for screen readers:

  @flagIconsCircle('br', ['alt' => 'Brazil'])
  

Gotchas and Tips

Pitfalls

1. Unsupported Country Codes:

   • The package only supports ISO 2-letter country codes (e.g., us, gb). Using unsupported codes (e.g., zz) will render nothing.
   • Fix: Validate country codes before rendering:

     use Moox\FlagIconsCircle\FlagIconsCircle;
     
     $supportedCodes = FlagIconsCircle::supportedCodes();
     if (in_array($countryCode, $supportedCodes)) {
         @flagIconsCircle($countryCode);
     } else {
         <!-- Fallback UI -->
     }
     

2. Missing SVG Assets:

   • If flags don’t render, check if the SVG files exist in public/vendor/moox/flag-icons-circle.
   • Fix: Republish assets:

     php artisan vendor:publish --provider="Moox\FlagIconsCircle\FlagIconsCircleServiceProvider" --tag="public"
     

3. Blade Component Not Found:

   • If you get Class 'FlagIcon' not found, ensure the service provider is registered in config/app.php.
   • Fix: Manually register the provider in config/app.php:

     'providers' => [
         // ...
         Moox\FlagIconsCircle\FlagIconsCircleServiceProvider::class,
     ],
     

4. Caching Issues:

   • Changes to flags may not reflect immediately due to Laravel’s caching.
   • Fix: Clear the config and view caches:

     php artisan config:clear
     php artisan view:clear
     

5. CSS Conflicts:

   • Default styles might conflict with your app’s CSS.
   • Fix: Scope the flags to a container or override styles:

     .flag-icon {
         width: 24px;
         height: 24px;
     }
     

Debugging

1. Check SVG Paths:

   • Open your browser’s DevTools (F12) and inspect the rendered flag. Verify the SVG path is correct (e.g., /vendor/moox/flag-icons-circle/us.svg).

2. Validate Country Codes:

   • Log the country code to ensure it’s correct:

     @dump($user->country_code)
     @flagIconsCircle($user->country_code)
     

3. Test in Isolation:

   • Create a minimal Blade file to test the flag rendering:

     @flagIconsCircle('us')
     

   • If it works here but not in your main app, the issue is likely in your layout or CSS.

Tips

1. Customizing Flags:

   • Publish the SVG assets and modify them:

     php artisan vendor:publish --tag="flag-icons-circle-svg"
     

   • Edit files in resources/svg/custom/ to add or override flags.

2. Dynamic Sizing:

   • Use the size attribute for predefined sizes (sm, md, lg, xl):

     @flagIconsCircle('in', ['size' => 'lg'])
     

   • Or use custom classes:

     @flagIconsCircle('mx', ['class' => 'w-8 h-8'])
     

3. Dark Mode Support:

   • Use CSS filters to invert colors for dark mode:

     @flagIconsCircle('kr', ['class' => 'dark:filter dark:invert'])
     

4. Performance Optimization:

   • For large lists, consider inlining SVGs or using a CDN to host the flag assets.

5. Extending the Package:

   • Create a custom Blade component that extends FlagIcon for additional functionality:

     namespace App\View\Components;
     
     use Moox\FlagIconsCircle\FlagIconsCircle;
     
     class CustomFlagIcon extends FlagIconsCircle
     {
         public function withTooltip($tooltip)
         {
             $this->withAttributes(['title' => $tooltip]);
             return $this;
         }
     }
     

   • Register the component in your service provider.

6. Fallback for Missing Flags:

   • Provide a fallback UI when a country code is unsupported:

     @if(in_array($countryCode, FlagIconsCircle::supportedCodes()))
         @flagIconsCircle($countryCode)
     @else
         <div class="w-6 h-6 bg-gray-200 rounded-full flex items-center justify-center">
             ?
         </div>