PHPackages                             nazariitsubera/country-aliases - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. nazariitsubera/country-aliases

ActiveLibrary[Utility & Helpers](/categories/utility)

nazariitsubera/country-aliases
==============================

ISO 3166-1 alpha-2 lookup for thousands of dirty country spellings, plus a PHP helper.

v1.0.0(5mo ago)12MITPHPPHP >=7.4

Since Nov 21Pushed 5mo agoCompare

[ Source](https://github.com/NazariiTsubera/country-aliases)[ Packagist](https://packagist.org/packages/nazariitsubera/country-aliases)[ RSS](/packages/nazariitsubera-country-aliases/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

Country alias normalizer
========================

[](#country-alias-normalizer)

This bundle packages the country alias lookup generated from the GeoNames datasets plus a thin PHP wrapper you can ship as a Composer package.

Structure
---------

[](#structure)

- `data/country_aliases.json` – Map `{normalized_name: "ISO2"}` for every unambiguous alias.
- `data/country_aliases.csv` – Two-column CSV (`normalized_name,iso2`) mirroring the JSON.
- `data/country_aliases_ambiguous.json` – Optional file with aliases that match more than one ISO2 code so you can handle them manually.
- `src/` – PHP wrapper exposing a simple runtime API.

Regenerate the data by rerunning the `build_country_aliases.py` script you used earlier (or fetch the latest GeoNames exports, then rebuild using the same normalization logic). The script should still trim, uppercase, strip accents, and ignore alternate names that look like URLs (strings starting with HTTP/HTTPS) so the output only contains actual country spellings. Once regenerated, drop the new files back into `data/`.

The JSON file is best suited for programmatic use (load once, look up millions of rows in-memory); the CSV is easier to scan manually.

PHP wrapper
-----------

[](#php-wrapper)

The `CountryAliasResolver` class in `src/` loads `data/country_aliases.json` and exposes a `lookup($value)` method that returns the ISO2 code (or `null` when no match exists). Example:

```
use CountryAliases\CountryAliasResolver;

$resolver = new CountryAliasResolver(__DIR__ . '/data/country_aliases.json');

var_dump($resolver->lookup('United States of America')); // "US"
var_dump($resolver->lookup('   republic   of   ireland  ')); // "IE"
```

Drop this repository into a Composer package (e.g., `country-aliases/country-aliases`), configure PSR-4 autoloading for `src/`, and you can normalize millions of dirty country strings with a single method call.

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance70

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

173d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1eadd4a458a42c4fde677a4fb7dcfabd9aa7a36771d071643bb260cd734ba4a3?d=identicon)[NazariiTsubera](/maintainers/NazariiTsubera)

---

Top Contributors

[![NazariiTsubera](https://avatars.githubusercontent.com/u/71921257?v=4)](https://github.com/NazariiTsubera "NazariiTsubera (3 commits)")

### Embed Badge

![Health badge](/badges/nazariitsubera-country-aliases/health.svg)

```
[![Health](https://phpackages.com/badges/nazariitsubera-country-aliases/health.svg)](https://phpackages.com/packages/nazariitsubera-country-aliases)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)