Countries Laravel Package

Getting Started

1. Install the package via Composer: composer require rinvex/countries.
2. Optionally publish the data file (if using Laravel): php artisan vendor:publish --provider="Rinvex\Country\CountryServiceProvider".
3. Start using it immediately — no service provider registration needed for framework-agnostic usage:

   $egypt = country('eg');
   echo $egypt->getName(); // "Egypt"
   

4. For Laravel apps, use the country() helper or Rinvex\Country\CountryLoader facade globally — it's autowired automatically via service provider.

Implementation Patterns

• Single country lookup: Use country($code) where $code is ISO 3166-1 alpha-2 (e.g., 'US', 'DE'), returning a Country DTO with rich methods.
• Bulk operations: Use countries() to get an array of all countries, or CountryLoader::all() for full objects.
• Querying with filters: Use CountryLoader::where('key.path', $values) for filtering:

  $africanCountries = \Rinvex\Country\CountryLoader::where('geo.continent', ['AF' => 'Africa']);
  

• Dynamic attribute access: Access properties directly (e.g., $country->name, $country->capital, $country->emoji) via magic getters.
• Formatting for UI:
  • Use getEmoji() for flag emojis (🇪🇬)
  • Use getFlag() to get SVG flag URLs or inline SVG (if assets are published).
  • Use getTranslations()['fr']['common'] to localize display names.
• Form integration (e.g., Laravel Nova, Filament):

  Select::make('Country')->options(
      collect(countries())->pluck('name', 'iso_alpha2')
  )
  

• Extended queries:
  • Get currencies with getCurrency() (single) or getCurrencies() (plural).
  • Fetch timezones via getTimezones() or geo coordinates via getGeoJson().

Gotchas and Tips

• ⚠️ Case sensitivity: ISO codes must be uppercase (e.g., 'US' not 'us'). Using lowercase may return null.
• ⚠️ Lazy loading: countries() returns a trimmed dataset for performance; CountryLoader::all() loads full data.
• 🔧 Extensibility: Extend CountryLoader to add custom queries or override the JSON loader for external data sources (e.g., add custom fields).
• 🐞 Debugging: Use getAttributes() to inspect raw data, or getData() to see the full decoded JSON structure.
• 💡 Caching: In high-traffic apps, cache countries() results in Redis or Memcached to avoid repeated JSON parsing.
• 🌐 Localization: getTranslations() returns nested per-language names — use getNativeNames() to get all native names keyed by language code.
• 🛠️ Data updates: The resources/data/countries.json is static. To update (e.g., for new currencies or ISO changes), replace the file manually or write a custom loader.
• 🗺️ Geo data quirk: geo.continent uses codes like "AF" as keys — ensure your filters match exact keys (not values like "Africa").
• 📐 Calling codes: Use getCallingCodes() (plural) — returns an array, not just getCallingCode().