Blade Country Flags Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require stijnvanouplines/blade-country-flags
   

   Publish the default flags (optional):

   php artisan vendor:publish --tag=blade-country-flags
   

2. Basic Usage Add the directive to your Blade template:

   @countryFlag('US')
   

   Outputs: <img src="/flags/US.svg" alt="US Flag" />

3. First Use Case Display a user’s country flag in a profile view:

   @countryFlag($user->country_code)
   

Implementation Patterns

Common Workflows

1. Dynamic Flag Rendering Loop through a collection of users and render flags:

   @foreach($users as $user)
       @countryFlag($user->country_code, ['class' => 'flag-icon'])
   @endforeach
   

2. Custom Flag Paths Override the default flag path in config/blade-country-flags.php:

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

3. Fallback Flags Provide a fallback for missing flags:

   @countryFlag($user->country_code, ['fallback' => 'GB'])
   

4. Inline SVG (No HTTP Requests) Use the svg option to render flags as inline SVG:

   @countryFlag('CA', ['svg' => true])
   

5. Integration with Eloquent Add an accessor to your User model:

   public function getCountryFlagAttribute()
   {
       return $this->country_code ? view('vendor.blade-country-flags.flag', ['code' => $this->country_code]) : null;
   }
   

   Usage in Blade:

   {!! $user->country_flag !!}
   

Advanced Patterns

1. Custom Flag Directives Extend the package by creating a custom directive (e.g., @flagLink):

   // app/Providers/BladeServiceProvider.php
   Blade::directive('flagLink', function ($expression) {
       return "<?php echo '<a href=\"'.route('country.profile', ['code' => {$expression}]).'\">'.\\Stijnvanouplines\\BladeCountryFlags\\Flag::render({$expression}).'</a>'; ?>";
   });
   

   Usage:

   @flagLink($user->country_code)
   

2. Caching Flags Cache rendered flags for performance:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       \Stijnvanouplines\BladeCountryFlags\Flag::setCacheEnabled(true);
   }
   

3. Multi-Language Support Combine with localization packages (e.g., laravel-localization):

   @countryFlag(app()->getLocale())
   

Gotchas and Tips

Pitfalls

1. Missing Flags

   • Ensure flags are published or manually placed in the configured path.
   • Debug with:

     @dump(\Stijnvanouplines\BladeCountryFlags\Flag::getFlagPath('US'))
     

2. Case Sensitivity Country codes are case-insensitive, but ensure consistency (e.g., always use uppercase).

3. Caching Issues Clear cached views if flags aren’t updating:

   php artisan view:clear
   

4. SVG vs. Image Inline SVG (svg: true) avoids HTTP requests but increases Blade template size. Benchmark for your use case.

Debugging Tips

1. Check Configuration Verify config/blade-country-flags.php paths and options:

   return [
       'path' => public_path('flags'),
       'default' => 'US',
       'svg' => false,
   ];
   

2. Log Missing Flags Add a fallback with logging:

   @countryFlag($user->country_code, [
       'fallback' => 'GB',
       'fallback_callback' => function ($code) {
           \Log::warning("Flag missing for country: {$code}");
       }
   ])
   

3. Custom Flag Sources Override the flag resolver in AppServiceProvider:

   \Stijnvanouplines\BladeCountryFlags\Flag::setResolver(function ($code) {
       return "https://custom-api.com/flags/{$code}.svg";
   });
   

Extension Points

1. Add New Flag Types Extend the Flag class to support emoji or other formats:

   // app/Extensions/CountryFlagEmoji.php
   namespace App\Extensions;
   use Stijnvanouplines\BladeCountryFlags\Flag;
   
   class CountryFlagEmoji extends Flag
   {
       public static function render($code, $options = [])
       {
           return \App\Extensions\Emoji::get($code);
       }
   }
   

2. Hook into Flag Rendering Use the rendering event:

   // app/Providers/EventServiceProvider.php
   public function boot()
   {
       \Stijnvanouplines\BladeCountryFlags\Events\Rendering::listen(function ($view, $code, $options) {
           // Modify $view or $options before rendering
       });
   }
   

3. Local Flag Overrides Override specific flags in resources/views/vendor/blade-country-flags/flags/US.blade.php:

   <img src="/custom-us-flag.svg" alt="US Flag" />