Php Isocodes Laravel Package

Product Decisions This Supports

• Globalization & Localization (G11N/L10N) Features:

  • Enables localized country, subdivision, language, currency, and script names for multilingual applications (e.g., e-commerce, SaaS platforms, or government services).
  • Supports ISO 3166-1/2/3, ISO 639-3, ISO 4217, and ISO 15924 standards, reducing manual data maintenance and ensuring compliance with international standards.
  • Example: A travel app displaying country names in the user’s preferred language (e.g., "Ukraine" → "Україна" for Ukrainian users).

• Data Integrity & Compliance:

  • Eliminates the need to manually update or validate ISO codes, reducing errors in regions, currencies, or languages (e.g., new countries like "South Sudan" or renamed currencies like "Euro").
  • Use case: Financial platforms requiring accurate currency names/abbreviations (e.g., "Czech Koruna" vs. "Czech Republic Koruna").

• Build vs. Buy Decision:

  • Buy: Avoid reinventing the wheel for ISO code management. The package is MIT-licensed, actively maintained (last release: 2025), and integrates with Laravel/Symfony ecosystems.
  • Build: Only if custom ISO extensions (e.g., proprietary subdivisions) are needed. Otherwise, the package’s flexibility (e.g., Symfony/Gettext drivers) reduces dev effort.

• Roadmap Priorities:

  • Phase 1: Integrate into user-facing features (e.g., dropdowns for country selection in forms).
  • Phase 2: Extend to backend systems (e.g., API responses, data validation).
  • Phase 3: Explore ISO 3166-2 subdivisions for granular regional targeting (e.g., US states, German Bundesländer).

• Performance vs. Accuracy Tradeoffs:

  • Choose php-isocodes-db-i18n for full localization (higher memory usage) or php-isocodes-db-only for lightweight code-only needs.
  • Optimize for memory (partitioned files) or speed (preloaded JSON) based on use case (e.g., CLI tools vs. web requests).

When to Consider This Package

Adopt This Package If:

• Your app requires localized ISO codes (e.g., user profiles, shipping addresses, financial transactions).
• You need standardized, up-to-date ISO data without manual updates (e.g., new countries, currency changes).
• You’re using Laravel/Symfony and want seamless integration with their translation systems (Gettext/Symfony Translation).
• Your team lacks bandwidth to maintain a custom ISO database or validate changes against ISO standards.

Look Elsewhere If:

• You need non-ISO codes (e.g., internal region IDs, custom hierarchies).
• Your app is extremely lightweight (e.g., embedded systems) and cannot tolerate the package’s memory footprint (~few MB for full DB).
• You require real-time ISO updates (this package updates via Composer/PHP scripts, not live APIs).
• You’re using a non-PHP stack (e.g., Node.js, Python) and prefer language-specific alternatives (e.g., pycountry for Python).

Alternatives to Evaluate:

How to Pitch It (Stakeholders)

For Executives (Business/Strategy):

"This package solves a critical gap in our global product roadmap: accurate, localized ISO codes for countries, languages, and currencies—without manual updates or compliance risks. For example:

• E-commerce: Display product prices in local currencies (e.g., €, $, ¥) with correct names (e.g., ‘Euro’ vs. ‘EUR’).
• Regulatory compliance: Automatically validate addresses using ISO 3166-2 subdivisions (e.g., US states, EU regions).
• User experience: Let customers select their country in their native language (e.g., ‘Brasil’ in Portuguese vs. ‘Brazil’ in English).

It’s a turnkey solution—MIT-licensed, actively maintained, and integrates with our Laravel stack. The cost? Zero (open-source) vs. the risk of errors or delays if we build this in-house. Let’s prioritize this for [Q1 roadmap] to enable [global expansion/market feature]."

For Engineering (Technical Feasibility):

"Problem: Managing ISO codes manually is error-prone, especially for languages/currencies that change (e.g., new countries, renamed currencies).

Solution: sokil/php-isocodes provides:

• Comprehensive ISO standards: 3166-1/2/3 (countries/subdivisions), 639-3 (languages), 4217 (currencies), 15924 (scripts).
• Localization support: Works with Symfony Translation (for Symfony apps) or Gettext (Laravel). Example:

  $country = (new IsoCodesFactory())->getCountries()->getByAlpha2('UA');
  echo $country->getLocalName(); // 'Україна' (Ukrainian)
  

• Flexible deployment:
  • Lightweight: php-isocodes-db-only (~1MB) for code-only needs.
  • Full i18n: php-isocodes-db-i18n (~5MB) for localized names.
  • Self-hosted updates: Run ./bin/update_iso_codes_db.sh via CI/CD or cron.
• Performance: Choose between partitioned files (low memory) or preloaded JSON (fast reads).

Integration:

• Laravel: Use the Symfony Translation driver or wrap in a service provider.
• Symfony: Native support via SymfonyTranslationDriver.
• Testing: Includes Dockerized tests for validation.

Risks:

• Memory usage (~5MB for full DB); mitigate by using db-only variant if localization isn’t needed.
• Dependency on Composer updates; schedule quarterly reviews to align with ISO changes.

Recommendation: Start with php-isocodes-db-i18n for [Feature X] and evaluate memory impact. If overhead is prohibitive, use db-only and add localization later via a separate translation layer."*

For Developers (Implementation):

*"Quick Start:

1. Install:

   composer require sokil/php-isocodes-db-i18n  # Full i18n
   # OR
   composer require sokil/php-isocodes-db-only  # Codes only
   

2. Basic usage:

   $isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
   $country = $isoCodes->getCountries()->getByAlpha2('US');
   echo $country->getName();       // 'United States'
   echo $country->getLocalName(); // Localized name (e.g., 'États-Unis' for French)
   

3. Symfony/Laravel: Configure the SymfonyTranslationDriver or GettextExtensionDriver for localization.

Pro Tips:

• For subdivisions (e.g., US states), use getSubdivisions()->getByCode('US-CA').
• Update DB: Run ./bin/update_iso_codes_db.sh all /path/to/storage in CI/CD.
• Memory optimization: Use partitioned mode (default) for low-memory environments.

Example Use Cases:

• Dropdowns: Populate country/language selectors with localized names.
• APIs: Return currency names in the user’s language (e.g., currency: { code: 'EUR', name: 'Euro' }).
• Validation: Check if a country code is valid (e.g., if ($isoCodes->getCountries()->hasAlpha2('ZZ')) { ... })."*