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

Description¶

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.

Impact¶

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();
$filter
    ->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:

<f:form.countrySelect
    name="country"
    value="AT"
    sortByOptionLabel="true"
    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.

Hint

A combination of optionLabelField and alternativeLanguage is possible. For instance, if you want to show the localized official names but not in your default language but in French. You can achieve this by using the following combination:

<f:form.countrySelect
    name="country"
    optionLabelField="localizedOfficialName"
    alternativeLanguage="fr"
    sortByOptionLabel="true"
/>