thalidzhokov / country-codes

1.2.1 2026-09-24 22:42 UTC

Requires

• php: ^5.6 || ^7.0 || ^8.0
• ext-json: *

GPL-3.0-or-later

• Albert Thalidzhokov

• iso
• 3166
• numeric
• country codes
• alpha-2
• alpha-3
• international organization for standardization
• iso-3166-1
• isd
• idd
• international direct dialing
• country calling codes
• country dial in codes
• international subscriber dialing

Published on Packagist.org on 2026-09-24 23:11 UTC

README

CountryCodes PHP Class to get array of countries with ISO 3166-1 alpha-2, ISO 3166-1 alpha-3, ISO 3166-1 numeric and ISD codes it can provide following information related to country

1. alpha2 ISO-3166-1 alpha-2 https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
2. alpha3 ISO-3166-1 alpha-3 https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
3. numeric ISO-3166-1 numeric https://en.wikipedia.org/wiki/ISO_3166-1_numeric
4. isd International Subscriber Dialing code https://en.wikipedia.org/wiki/List_of_country_calling_codes
5. continentCode Continent Code
6. continent Continent Name
7. country Country Name
8. countryFull Country Full Name
9. emoji Emoji Flag http://unicode.org/emoji/charts/emoji-ordering.html#country-flag

Names are available in English (en) and Russian (ru). The data is stored in CountryCodes.jsonc.

Installation

Install via Composer

composer require thalidzhokov/country-codes

OR include CountryCodes.php in your PHP code

require_once('CountryCodes.php');

Usage

Change default language

\CountryCodes::$language = 'ru';

Methods get(), get2() and getByContinent() also take the language as the last argument. An unsupported language falls back to en.

Method get()

Get array key => value

\CountryCodes::get('alpha2', 'country');
\CountryCodes::get('alpha2', 'country', 'ru');

If $keyField is null or not a supported field, the result is a list without keys. If $requestedField is not supported, country is used.

Return

array (
  'AB' => 'Abkhazia',
  'AD' => 'Andorra',
  ...,
  'AI' => 'Anguilla',
  'AL' => 'Albania',
  'AM' => 'Armenia',
  ...,
  'US' => 'USA',
  ...
)

Repeated keys

If several countries share a key (e.g. isd), the value becomes an array of all their values

\CountryCodes::get('isd', 'alpha2');

Return

array (
  1 => 
  array (
    0 => 'CA',
    1 => 'PR',
    2 => 'UM',
    3 => 'US',
  ),
  ...,
  93 => 'AF',
  ...
)

The same applies to get2() and getByContinent().

Method get2()

Get array with multiple values key => [value1, value2, ...]

\CountryCodes::get2('alpha3', ['alpha2', 'continentCode', 'emoji']);

Return

array (
  'ABH' => 
  array (
    'alpha2' => 'AB',
    'continentCode' => 'AS',
    'emoji' => '',
  ),
  'AND' => 
  array (
    'alpha2' => 'AD',
    'continentCode' => 'EU',
    'emoji' => '🇦🇩',
  ),
  'ARE' => 
  array (
    'alpha2' => 'AE',
    'continentCode' => 'AS',
    'emoji' => '🇦🇪',
  ),
  ...
)

Method getByContinent()

Get array key => value by continent

\CountryCodes::getByContinent('alpha3', 'countryFull', 'EU');

Continent codes: AF, AN, AS, EU, NA, OC, SA (case-insensitive). An empty code returns all countries, an unknown code returns an empty array.

Return

array (
  ...,
  'BEL' => 'Belgium',
  'BGR' => 'Bulgaria',
  'BLR' => 'Belarus',
  'CHE' => 'Swiss Confederation',
  'CZE' => 'Czech Republic',
  'DEU' => 'Germany',
  ...
)

Method getEmojiByAlpha2()

Get emoji flag code by alpha2 as HTML entities. Returns an empty string for unknown codes and for AB, OS, XK: Unicode has no flags for them.

\CountryCodes::getEmojiByAlpha2('ZW');

Return

🇿🇼

Method getEmojiByAlpha3()

Get emoji flag code by alpha3. Also accepts ENG, WLS / WAL, SCT / SCO for England, Wales and Scotland flags.

\CountryCodes::getEmojiByAlpha3('ZMB');

Return

🇿🇲

Tests

composer test
# or
php tests/functional.php