league/iso3166

league/iso3166 is a PHP library that provides the ISO 3166-1 standard’s country data: two-letter alpha-2 codes, three-letter alpha-3 codes, three-digit numeric codes, country names, and associated currencies. It packages this reference data behind a small, dependency-free lookup API so applications can validate and translate country identifiers reliably.

Maintained under The PHP League, the library keeps the dataset current and exposes convenient lookups by any of the code types or by name. An optional aliases layer maps common alternative country names to their canonical entries, making it practical for real-world user input.

What You Get

• Complete ISO 3166-1 country data: alpha-2, alpha-3, numeric codes, names, and currencies
• A simple lookup API to resolve countries by any code type or name
• Input guards that raise descriptive exceptions on invalid or unknown codes
• An aliases decorator that maps alternative country names to canonical entries
• Zero runtime dependencies and full iteration over the dataset

Common Use Cases

• Validating a user-supplied country code during checkout or registration
• Converting between alpha-2, alpha-3, and numeric country codes
• Populating country dropdowns with canonical names and codes
• Enriching records with currency or naming data derived from a country code

Under The Hood

Architecture - The core is src/ISO3166.php, which loads a large static array of country records and implements the ISO3166DataProvider contract with lookup methods (alpha2, alpha3, numeric, name, all). src/Guards.php centralizes input validation, src/ISO3166DataValidator.php enforces dataset integrity, and src/ISO3166WithAliases.php decorates the provider to resolve alternative names. Errors surface through dedicated classes in src/Exception.

Tech Stack - Pure PHP with no runtime dependencies; the dataset is embedded as PHP arrays rather than loaded from external files at runtime. Development tooling includes PHPUnit for testing and standard PSR-4 autoloading under the ISO3166 namespace.

Code Quality - The tests directory covers the main lookup class, the aliases decorator, and the data validator (ISO3166Test, ISO3166WithAliasesTest, ISO3166DataValidatorTest). A dedicated validator guards against malformed data, and the small surface area keeps behavior easy to reason about and maintain.

API Design - The API is minimal and predictable: instantiate ISO3166 and call alpha2(), alpha3(), numeric(), name(), or all(). Consistent method naming mirrors the standard’s code types, and exceptions make failure modes explicit, so integrating country lookups takes only a few lines.