Blade Flags Laravel Package

## Getting Started

### Minimal Steps
1. **Installation**:
   ```bash
   composer require outhebox/blade-flags

For frontend frameworks:

npm install @blade-flags/core @blade-flags/vue  # Vue
npm install @blade-flags/core @blade-flags/react # React

2. First Use Case: Insert a country flag in a Blade view:

   <x-flag-country-us />
   

   Or a language flag:

   <x-flag-language-en />
   

3. Where to Look First:

   • README.md for Blade syntax
   • SVG directories for available flags
   • Blade Icons docs for caching and advanced usage

Implementation Patterns

Blade Integration

1. Static Flags: Use predefined components for known flags:

   <x-flag-circle-country-gb class="w-8 h-8" />
   <x-flag-flat-language-es />
   

2. Dynamic Flags: Use @svg directive for runtime-generated flag names:

   @svg('flag-country-'.$user->country_code)
   @svg('flag-circle-language-'.$user->language_code, ['class' => 'text-blue-500'])
   

3. Helper Method:

   // In a controller or service
   public function getFlagSvg($countryCode) {
       return svg("flag-country-{$countryCode}")->toHtml();
   }
   

Frontend Integration (Vue/React)

1. Dynamic Rendering:

   <script setup>
   import { Flag } from '@blade-flags/vue'
   import { circleFlags } from '@blade-flags/core/flags/circle'
   </script>
   
   <template>
     <Flag :code="user.country" :flags="circleFlags" />
   </template>
   

2. Tree-Shaking: Import only needed flags for static use:

   import { countryUs, languageAr } from '@blade-flags/core/flags/circle'
   

3. Inertia.js: Pass flag data from Laravel to Vue/React via page props:

   return Inertia::render('Profile', [
       'user' => $user,
       'flags' => ['country' => $user->country_code, 'language' => $user->language_code]
   ]);
   

Common Workflows

1. Locale Switcher:

   <div class="flex gap-2">
       @foreach($availableLanguages as $lang)
           <x-flag-circle-language-{{ $lang->code }} class="cursor-pointer"
               wire:click="changeLanguage('{{ $lang->code }}')"/>
       @endforeach
   </div>
   

2. User Profile:

   <div class="flex items-center gap-3">
       <x-flag-country-{{ $user->country }} class="w-10 h-8" />
       <span>{{ $user->name }}</span>
   </div>
   

3. Admin Dashboard:

   <table>
       @foreach($users as $user)
           <tr>
               <td><x-flag-country-{{ $user->country }} /></td>
               <td>{{ $user->name }}</td>
           </tr>
       @endforeach
   </table>
   

Gotchas and Tips

Pitfalls

1. CSS Sizing:

   • Flags may ignore Tailwind classes like w-6 h-6 if hardcoded width/height exists in SVG.
   • Fix: Use width="100%" height="100%" in SVG or wrap in a container with explicit dimensions.
   • Example:

     <div class="w-6 h-6">
         <x-flag-country-us />
     </div>
     

2. Missing Flags:

   • Not all countries/languages are supported (check SVG directories).
   • Workaround: Use regional variants (e.g., en-us instead of en) or fall back to a generic flag.

3. Caching:

   • Blade Icons (underlying package) caches SVGs. Clear cache if flags don’t update:

     php artisan view:clear
     php artisan cache:clear
     

4. Dynamic Flag Names:

   • Ensure $country->iso2_code or $language->code matches the package’s naming convention (e.g., us, en, ar-sa).
   • Debug: Check available flags in resources/svg/ or use php artisan tinker to inspect:

     \Outhebox\BladeFlags\Facades\BladeFlags::availableFlags();
     

Debugging

1. Inspect SVG Output:

   {{ \Outhebox\BladeFlags\Facades\BladeFlags::svg('flag-country-us')->toHtml() }}
   

   Look for malformed tags or missing attributes.

2. Check Published Assets: If using raw SVGs, verify they exist in:

   public/vendor/blade-flags/country-us.svg
   

3. Frontend Debugging:

   • For Vue/React, log the resolved flag code:

     console.log(resolveFlag(circleFlags, 'us')); // Check if SVG is valid
     

Configuration Quirks

1. Language Overrides:

   • Overrides require republishing SVGs:

     php artisan vendor:publish --tag=blade-flags-config
     php artisan blade-flags:generate
     

2. Blade Icons Compatibility:

   • If using Blade Icons’ BladeIcon::resolve(), ensure the package is installed:

     composer require blade-ui-kit/blade-icons
     

3. Inertia.js:

   • Flags in Vue/React must match the variant (e.g., circleFlags) used in Blade for consistency.

Extension Points

1. Custom Flags:

   • Add your own SVGs to public/vendor/blade-flags/ and reference them via @svg('custom-flag').

2. Flag Variants:

   • Extend the package by creating a new variant (e.g., square-flags) by copying the build script and SVG templates.

3. Dynamic Generation:

   • Use the resolveFlag() helper to build flags programmatically:

     $svg = \Outhebox\BladeFlags\Facades\BladeFlags::resolve('circle', 'country', 'us');
     

Performance Tips

1. Tree-Shaking:

   • For static flags, import individual flags to reduce bundle size:

     import { countryUs, countryGb } from '@blade-flags/core/flags/circle';
     

2. Lazy Loading:

   • Load flags dynamically in SPAs to reduce initial load time:

     const loadFlag = async (code) => {
         const { resolveFlag, circleFlags } = await import('@blade-flags/core');
         return resolveFlag(circleFlags, code);
     };
     

3. Blade Caching:

   • Disable caching for development:

     // config/blade-flags.php
     'cache' => env('APP_ENV') !== 'local',
     

Pro Tips

1. Combine with Blade Icons:

   • Use Blade Icons’ features like size and color:

     <x-flag-country-us size="2x" color="#0000FF" />
     

2. Dark Mode:

   • Override SVG colors for dark mode:

     <x-flag-country-us class="dark:invert" />
     

3. Accessibility:

   • Add aria-label for screen readers:

     <x-flag-country-us aria-label="United States" />
     

4. Regional Variants:

   • Use - for regional flags (e.g., ar-sa for Arabic-Saudi Arabia):

     <x-flag-circle-language-ar-sa />
     

5. Testing:

   • Test dynamic flags with edge cases:

     // Test invalid flag codes
     $this->blade->render('@svg("flag-country-xx")')->assertSee('Invalid flag code');
     

---