Laravel Iso Countries Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require arthurydalgo/laravel-iso-countries
   

   No migrations are required—data is stored in a pre-built SQLite database.

2. Publish Config (Optional):

   php artisan vendor:publish --provider="Io238\ISOCountries\ISOCountriesServiceProvider" --tag="config"
   

   Default config includes en, de, fr, and es locales.

3. Rebuild Database (If Needed):

   php artisan db:seed countries:build
   

   Exclude database/iso-countries.sqlite from .gitignore to share across environments.

4. First Use Case: Fetch a country by ISO code:

   use Io238\ISOCountries\Models\Country;
   $country = Country::find('US'); // Returns Country model with localized names
   

Implementation Patterns

Core Workflows

1. Localized Data Access: Dynamically fetch names in the app’s locale:

   app()->setLocale('fr');
   Country::find('FR')->name; // Returns "France" in French
   

2. Relationship Queries: Leverage built-in relationships for multi-directional lookups:

   // Countries using EUR
   Currency::find('EUR')->countries;
   
   // Languages spoken in Brazil
   Country::find('BR')->languages;
   

3. Casting ISO Codes: Enrich existing models with metadata via custom casts:

   use Io238\ISOCountries\Casts\Country;
   
   class User {
       protected $casts = ['country_code' => Country::class];
   }
   // Now `$user->country_code` returns a Country model.
   

4. Filtering by Region/Attributes: Use Eloquent queries with ISO data:

   // Top 5 populated countries in Asia
   Country::where('region', 'Asia')
           ->orderByDesc('population')
           ->limit(5)
           ->pluck('name');
   

5. Multi-Language Support: Extend translations by updating the config and rebuilding the database:

   // config/iso-countries.php
   'locales' => ['en', 'es', 'pt'],
   

   Then run php artisan db:seed countries:build.

Integration Tips

• Validation: Use ISO codes in form requests:

  use Illuminate\Validation\Rule;
  $request->validate([
      'country' => ['required', Rule::exists('iso_countries', 'id')],
  ]);
  

• API Responses: Serialize localized data:

  return Country::find('CA')->only(['name', 'capital', 'currencies']);
  

• Admin Panels: Display flags using flag-icon-css (included):

  <img src="{{ asset('vendor/flag-icon-css/flags/1x1/{{ $country->id }}.svg') }}" alt="{{ $country->name }}">
  

Gotchas and Tips

Pitfalls

1. Database Path:

   • Forgetting to exclude iso-countries.sqlite from .gitignore can bloat repositories.
   • Fix: Add !iso-countries.sqlite to .gitignore.

2. Locale Fallback:

   • If a locale isn’t in the config, the app falls back to app.fallback_locale. Ensure this is set in config/app.php.

3. Rebuilding Data:

   • Rebuilding the database (countries:build) overwrites existing data. Backup if needed.

4. Performance:

   • The SQLite database is lightweight (~5MB), but avoid eager-loading all relationships in bulk queries.

Debugging

• Missing Data: Check if the locale is included in config/iso-countries.php. Rebuild the database if needed.
• Relationship Errors: Ensure the id field in your models matches the ISO code (e.g., country_code = 'US').

Extension Points

1. Custom Attributes: Add computed properties to models:

   class Country extends \Io238\ISOCountries\Models\Country {
       public function getFullNameAttribute() {
           return $this->name . " (Capital: {$this->capital})";
       }
   }
   

2. Additional Translations: Fork the package and extend the data source (see CONTRIBUTING).
3. Custom Relationships: Override relationships in a service provider:

   Country::query()->macro('byRegion', function ($region) {
       return $this->where('region', $region);
   });
   

Pro Tips

• Cache Frequently Used Data:

  $euroCountries = Cache::remember('euro_countries', now()->addDays(7), function () {
      return Currency::find('EUR')->countries->pluck('name');
  });
  

• Use in Policies: Restrict access by country:

  public function before($user, $ability) {
      if ($user->country_code === 'US') {
          return true;
      }
  }
  

• Testing: Mock the models in tests:

  $this->mock(Io238\ISOCountries\Models\Country::class, function ($mock) {
      $mock->shouldReceive('find')->andReturn(new Country(['id' => 'US']));
  });