Feature: #99618 - List of countries in the world and their localized names

See forge#99618


TYPO3 now ships a list of countries of the world. The list is based on the ISO 3166-1 standard, with the alpha-numeric short name ("FR" or "FRA" in its three-letter short name), the English name ("France"), the official name ("Republic of France"), also the numerical code, and the country's flag as emoji (UTF-8 representation).

This list is based on Debian's ISO code list https://salsa.debian.org/iso-codes-team/iso-codes, and shipped statically as PHP content in a new country API.


It is now possible to load a list of all countries via PHP:

use TYPO3\CMS\Core\Utility\GeneralUtility;

$countryProvider = GeneralUtility::makeInstance(CountryProvider::class);
$france = $countryProvider->getByIsoCode('FR');
// or
$france = $countryProvider->getByEnglishName('France');
// or
$france = $countryProvider->getByAlpha3IsoCode('FRA');
// or
$allCountries = $countryProvider->getAll();
// or
$filter = new CountryFilter();
    ->setOnlyCountries(['AT', 'DE', 'FR', 'DK'])
    ->setExcludeCountries(['AUT', 'DK']);
$filteredCountries = $countryProvider->getFiltered($filter); // will be array with DE & FR

A country object can be used to fetch all information about this, also with translatable labels:

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Localization\LanguageServiceFactory;

$languageService = GeneralUtility::makeInstance(LanguageServiceFactory::class)->create('de');
echo $france->getName();    // "France"
echo $languageService->sL($france->getLocalizedNameLabel()); // "Frankreich"
echo $france->getOfficialName();    // "French Republic"
echo $languageService->sL($france->getLocalizedOfficalNameLabel()); // "Französische Republik"
echo $france->getNumericRepresentation(); // 250
echo $france->getAlpha2IsoCode(); // "FR"
echo $france->getFlag(); // "🇫🇷"

A Fluid ViewHelper is also shipped with TYPO3 to render a dropdown for forms:

    prioritizedCountries="{0: 'DE', 1: 'AT', 2: 'CH'}"

Available options

  • disabled: Specifies that the form element should be disabled when the page loads.
  • required: If set no empty value is allowed.
  • size: Size of select field, a numeric value to show the amount of items to be visible at the same time - equivalent to HTML <select> site attribute
  • multiple: If set multiple options may be selected
  • errorClass: Specify the CSS class to be set if there are errors for this ViewHelper.
  • sortByOptionLabel: Whether the country list should be sorted by option label or not.
  • optionLabelField: Specify the type of label of the country list. Available options are: "name", "localizedName", "officialName" or "localizedOfficialName". Default option is "localizedName".
  • alternativeLanguage: If specified, the country list will be shown in the given language.
  • prioritizedCountries: Define a list of countries which should be listed as first options in the form element.
  • onlyCountries: Restrict the countries to be rendered in the list.
  • excludeCountries: Define which countries should not be shown in the list.
  • prependOptionLabel: Provide an additional option at first position with the specified label.
  • prependOptionValue: Provide an additional option at first position with the specified value.