Native Country Names Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel-lang/native-country-names
   

   Publish the config (optional):

   php artisan vendor:publish --provider="LaravelLang\NativeCountryNames\ServiceProvider"
   

2. First Use Case: Display a country name in the current app locale:

   use LaravelLang\NativeCountryNames\Facades\Country;
   
   // In a Blade template or controller
   $countryName = Country::name('US'); // Returns "United States" (en) or localized equivalent
   

3. Where to Look First:

   • Facade: Country (e.g., Country::name(), Country::all()).
   • Config: config/native-country-names.php (custom locales, paths).
   • Documentation: Laravel Lang Docs.

Implementation Patterns

Core Workflows

1. Locale-Aware Country Names:

   // Auto-detects app locale (config/app.php)
   Country::name('GB'); // "United Kingdom" (en) or "Royaume-Uni" (fr)
   
   // Force a specific locale
   Country::setLocale('de');
   Country::name('GB'); // "Vereinigtes Königreich"
   

2. Dropdowns/Forms:

   <select name="country">
       @foreach (Country::all() as $code => $name)
           <option value="{{ $code }}">{{ $name }}</option>
       @endforeach
   </select>
   

   • Optimization: Cache Country::all() if used frequently (e.g., in a global dropdown).

3. API Responses:

   return Country::all(); // Returns array like:
   // ['US' => 'United States', 'GB' => 'United Kingdom', ...]
   

4. Dynamic Localization:

   $userLocale = $user->locale ?? app()->getLocale();
   Country::setLocale($userLocale);
   $countryName = Country::name($request->country_code);
   

Integration Tips

• Validation: Use with Laravel’s Rule::in() for country code validation:

  use LaravelLang\NativeCountryNames\Rules\Country;
  
  $request->validate([
      'country' => ['required', new Country],
  ]);
  

• Blade Directives: Create a custom directive for reusable country names:

  Blade::directive('country', function ($code) {
      return "<?php echo LaravelLang\NativeCountryNames\Facades\Country::name({$code}); ?>";
  });
  

  Usage:

  <p>Selected: @country('CA')</p>
  

• Database Storage: Store country codes (e.g., US) and fetch names dynamically:

  $user->country_name = Country::name($user->country_code);
  

• Testing: Mock the facade for unit tests:

  $this->app->shouldReceive('getLocale')->andReturn('es');
  $this->assertEquals('España', Country::name('ES'));
  

Gotchas and Tips

Pitfalls

1. Locale Fallback:

   • If a locale isn’t supported, the package falls back to English. Ensure your app’s fallback locale (config/app.php) is set correctly.
   • Fix: Add missing locales via the Laravel Lang GitHub or extend the package (see below).

2. Caching:

   • Country::all() loads the entire dataset. Cache it in a high-traffic app:

     $countries = Cache::remember('countries', now()->addHours(1), function () {
         return Country::all();
     });
     

3. Country Code Sensitivity:

   • Codes are case-sensitive (e.g., US ≠ us). Use strtoupper() if accepting user input:

     $code = strtoupper($request->country);
     

4. Data Updates:

   • The package updates data via GitHub Actions. For custom datasets, manually update vendor/laravel-lang/native-country-names/data/ (not recommended for production).

Debugging

• Missing Locales: Check config/native-country-names.php for supported locales. Add custom locales by extending the package (see below).
• Performance: Profile Country::all() with tideways/xhprof if slow. Optimize with caching or lazy-loading.
• Edge Cases: Some countries have multiple names (e.g., "Czech Republic" vs. "Czechia"). The package uses the most common native name; override via config:

  'overrides' => [
      'CZ' => 'Česko', // Force "Czechia" in supported locales
  ],
  

Extension Points

1. Add Custom Locales:

   • Extend the Country facade or create a decorator:

     use LaravelLang\NativeCountryNames\Facades\Country as BaseCountry;
     
     class ExtendedCountry extends BaseCountry {
         public static function name($code, $locale = null) {
             $locale = $locale ?: app()->getLocale();
             $customNames = [
                 'XK' => ['kos' => 'Kosovë'], // Albanian name for Kosovo
             ];
             return $customNames[$code][$locale] ?? parent::name($code, $locale);
         }
     }
     

   • Bind the decorator in a service provider:

     app()->bind('LaravelLang\NativeCountryNames\Facades\Country', function () {
         return new ExtendedCountry();
     });
     

2. Override Data Source:

   • Replace the default data path in config/native-country-names.php:

     'data_path' => database_path('country-names.json'),
     

   • Populate the JSON file with your custom dataset (must match the package’s structure).

3. Add Country-Specific Logic:

   • Use events or middleware to modify country names dynamically:

     Country::name('US'); // "United States"
     Country::name('US', 'fr'); // "États-Unis"
     Country::name('US', 'custom'); // "Custom Name" (via middleware)
     

Tips

• Laravel 13+: Use the app() helper for locale access:

  $locale = app()->getLocale();
  

• Testing: Use Country::setLocale() to test specific locales:

  Country::setLocale('ja');
  $this->assertEquals('アメリカ合衆国', Country::name('US'));
  

• Contributing: Submit missing locales via Laravel Lang’s contribution guide.
• Fallback Logic: Handle unsupported locales gracefully:

  $name = Country::name($code, $locale);
  $name = $name ?? trans('countries.'.$code, [], $locale); // Fallback to custom translations