Iso3166 Laravel Package

Getting Started

1. Install via Composer: composer require league/iso3166.
2. Instantiate the League\ISO3166\ISO3166 class and use its lookup methods:

   $iso = new League\ISO3166\ISO3166;
   $france = $iso->alpha2('FR');
   $germany = $iso->name('Germany');
   

3. Start with basic lookups: alpha2(), alpha3(), numeric(), or name(). All return an associative array containing country data, or null if not found.
4. Check exactName() if case- and diacritic-insensitive partial matches aren’t desired — useful for strict validation (added in v4.3.0).
5. Use all() to retrieve all countries as an array, or count() to get the total number of entries.

Implementation Patterns

• Form validation / user input normalization: Normalize country inputs (e.g., from dropdowns or text fields) to alpha2/alpha3 codes. For example:

  $countryCode = $iso->alpha2($request->get('country_name'));
  

  Allow users to input names, then store only standardized codes in the database.

• Lookup in domain entities: Inject ISO3166 into services or domain models to enrich value objects (e.g., Address, Customer):

  public function getCurrency(string $alpha2): ?string
  {
      $data = $this->iso3166->alpha2($alpha2);
      return $data['currency'][0] ?? null;
  }
  

• Data exports & integrations: Enrich datasets (e.g., order shipments, CRM records) with ISO-compliant codes for reporting or external API integrations (e.g., tax engines, customs systems).

• Static caching for performance: Reuse the same instance or wrap it in a Laravel service provider for singleton usage. The class is stateless, but avoiding repeated new instances improves efficiency in loops.

• Laravel integration patterns:

  • Bind ISO3166 as a singleton in AppServiceProvider.
  • Use in form request validation: create custom rules like new class implements Rule that checks iso->alpha2($value).
  • Combine with locales for multilingual names if extended with aliases (e.g., “Congo” → “Democratic Republic of the Congo” — added in v4.2.0 & v4.3.1).

Gotchas and Tips

• Partial vs exact matching: name() uses case-insensitive partial match (v4.1.0+), so name('united') may return multiple results or unexpected matches (first match wins via internal iteration). Prefer exactName() for strict name lookups.
• Currency format: The currency key is always an array, even if only one currency exists (e.g., ['EUR']). Never assume scalar.
• Missing countries: Kosovo (XK) was added in v4.3.2; older versions omit it. If your use case depends on Kosovo, ensure you’re on ≥ v4.3.2.
• Unicode safety: Since v4.1.0, lookups handle multibyte strings (e.g., diacritics in “Zürich” or “Álvarez”), but match only on official English names — not localized names.
• Performance tip: In tight loops or CLI jobs, avoid repeated new ISO3166() calls; cache a single instance.
• Extensibility: You can inject a custom data provider to override or extend country data (e.g., add internal aliases), but this is rarely needed. Use only if data drifts from official ISO or you need project-specific mappings.
• Nullable return types matter: Methods return ?array — always guard against null or use null coalescing (?? []).
• Stale data? Data updates depend on community contributions. Check the changelog and open issues if recent geopolitical changes (e.g., new countries, name updates) don’t appear. As of v4.4.0, Bulgaria’s currency was updated to EUR (2026-01-01), showing active maintenance.