README

A library for handling language data, country codes, timezones, TLD lookups and IP-to-country resolution.

Installation

composer require horde/nls

Optional dependencies

# For reverse-DNS hostname lookups
composer require mikepultz/netdns2

# For MaxMind GeoIP2/GeoLite2 database lookups
composer require geoip2/geoip2

Usage

Basic usage (injectable service)

use Horde\Nls\Nls;

$nls = new Nls();

// Country lookup
$nls->countries()->get('DE');          // 'Germany'
$nls->countries()->all();              // ['AD' => 'Andorra', 'AE' => 'United Arab Emirates', ...]
$nls->countries()->translated();       // Localized names, sorted by locale

// Language lookup
$nls->languages()->get('fr');          // 'French'

// Timezones
$nls->getTimezones();                  // ['Africa/Abidjan' => 'Africa/Abidjan', ...]

// Charset validation
$nls->checkCharset('UTF-8');           // true
$nls->checkCharset('NOT-REAL');        // false

Data classes as arrays

All data classes implement IteratorAggregate, ArrayAccess, and Countable:

$countries = new \Horde\Nls\Countries();

foreach ($countries as $code => $name) {
    echo "$code: $name\n";
}

echo $countries['US'];     // 'United States'
echo count($countries);    // 249
isset($countries['XX']);   // false

Translation (explicit)

Translation is never applied implicitly. Call translated() when you need localized output:

$countries = new \Horde\Nls\Countries();

$countries->all();         // English names (default)
$countries->translated();  // Localized via gettext, sorted by locale

Country lookup from hostname/IP

use Horde\Nls\Nls;
use Horde\Nls\Dns\NativeResolver;
use Horde\Nls\Geoip\Geoip2Driver;

$nls = new Nls(
    resolver: new NativeResolver(),
    geoip: new Geoip2Driver('/path/to/GeoLite2-Country.mmdb'),
);

$result = $nls->getCountryByHost('example.de');
// ['code' => 'de', 'name' => 'Germany']

$result = $nls->getCountryByHost('8.8.8.8');
// ['code' => 'us', 'name' => 'United States'] (via GeoIP)

Legacy code resolution

Retired ISO-3166 codes and old country names are handled by LegacyCodes:

$legacy = new \Horde\Nls\LegacyCodes();

$legacy->resolve('AN');                    // 'BQ' (Netherlands Antilles → Bonaire)
$legacy->resolve('YU');                    // 'RS' (Yugoslavia → Serbia)
$legacy->resolveName('Czech Republic');    // 'CZ'
$legacy->resolveName('Swaziland');         // 'SZ'

GeoIP drivers

use Horde\Nls\Geoip\Geoip2Driver;
use Horde\Nls\Geoip\LegacyDatDriver;
use Horde\Nls\Geoip\NullDriver;

// MaxMind GeoIP2 (recommended)
$geoip = new Geoip2Driver('/path/to/GeoLite2-Country.mmdb');

// Legacy .dat format
$geoip = new LegacyDatDriver('/path/to/GeoIP.dat');

// No GeoIP (default)
$geoip = new NullDriver();

DNS resolvers

use Horde\Nls\Dns\NullResolver;
use Horde\Nls\Dns\NativeResolver;
use Horde\Nls\Dns\NetDns2Resolver;

// No reverse DNS (default)
$resolver = new NullResolver();

// PHP built-in gethostbyaddr
$resolver = new NativeResolver();

// NetDNS2 library
$resolver = new NetDns2Resolver($netdns2Instance);

Architecture

src/
├── Nls.php                          # Main injectable service
├── Translation.php                  # Horde\Translation integration
├── Countries.php                    # ISO-3166 country data
├── Languages.php                    # ISO-639-1 language data
├── Tld.php                          # TLD → country mapping
├── Alpha3.php                       # Alpha-2 → Alpha-3 codes
├── Carsigns.php                     # License plate prefixes
├── LegacyCodes.php                  # Retired code resolution
├── Coordinates/
│   ├── CoordinatesInterface.php     # Provider contract
│   └── StaticCoordinates.php        # Bundled city data
├── Dns/
│   ├── ResolverInterface.php        # Reverse DNS contract
│   ├── NullResolver.php
│   ├── NativeResolver.php
│   └── NetDns2Resolver.php
├── Geoip/
│   ├── GeoipInterface.php           # IP→country contract
│   ├── Geoip2Driver.php             # MaxMind GeoIP2/GeoLite2
│   ├── LegacyDatDriver.php          # MaxMind legacy .dat
│   └── NullDriver.php
└── DataRegeneration/
    └── IanaTldUpdater.php           # IANA TLD list updater

Upgrading from Horde_Nls

See doc/UPGRADING.md for a complete migration guide from the legacy Horde_Nls static API to the new injectable Horde\Nls\Nls service.

Requirements

• PHP 8.1+
• ext-mbstring
• horde/translation ^3

License

LGPL-2.1-only. See LICENSE for details.