Country API

New in version 12.2.

TYPO3 ships a list of countries of the world. The list is based on the ISO 3166-1 standard, with the alphanumeric 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).

Note

The country list is based on Debian's ISO code list and shipped statically as PHP content in the Country API.

Using the PHP API

Dependency injection can be used to retrieve the \TYPO3\CMS\Core\Country\CountryProvider class:

EXT:my_extension/Classes/MyClass.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Country\CountryProvider;

final class MyClass
{
    public function __construct(
        private readonly CountryProvider $countryProvider
    ) {}
}

Get all countries

To get all countries call the getAll() method:

EXT:my_extension/Classes/MyClass.php
$allCountries = $this->countryProvider->getAll();

The method returns an array of \TYPO3\CMS\Core\Country\Country objects.

Get a country

EXT:my_extension/Classes/MyClass.php
// Get the country by Alpha-2 code
$france = $this->countryProvider->getByIsoCode('FR');

// Get the country by name
$france = $this->countryProvider->getByEnglishName('France');

// Get the country by Alpha-3 code
$france = $this->countryProvider->getByAlpha3IsoCode('FRA');

The methods return a \TYPO3\CMS\Core\Country\Country object.

Filter countries

One can use filters to get the desired countries:

EXT:my_extension/Classes/MyClass.php
use TYPO3\CMS\Core\Country\CountryFilter;

$filter = new CountryFilter();

// Alpha-2 and Alpha-3 ISO codes can be used
$filter
    ->setOnlyCountries(['AT', 'DE', 'FR', 'DK'])
    ->setExcludeCountries(['AUT', 'DK']);

// Will be an array with "Germany" and "France"
$filteredCountries = $this->countryProvider->getFiltered($filter);

The method getFiltered() return an array of \TYPO3\CMS\Core\Country\Country objects.

The Country object

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

EXT:my_extension/Classes/MyClassWithTranslation.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Country\CountryProvider;
use TYPO3\CMS\Core\Localization\LanguageServiceFactory;
use TYPO3\CMS\Core\Localization\Locale;

final class MyClassWithTranslation
{
    public function __construct(
        private readonly CountryProvider $countryProvider,
        private readonly LanguageServiceFactory $languageServiceFactory
    ) {}

    public function doSomething()
    {
        $languageService = $this->languageServiceFactory->create(new Locale('de'));
        $france = $this->countryProvider->getByIsoCode('FR');

        // "France"
        $france->getName();

        // "Frankreich"
        $languageService->sL($france->getLocalizedNameLabel());

        // "French Republic"
        echo $france->getOfficialName();

        // "Französische Republik"
        $languageService->sL($france->getLocalizedOfficialNameLabel());

        // 250
        $france->getNumericRepresentation();

        // "FR"
        $france->getAlpha2IsoCode();

        // "🇫🇷"
        $france->getFlag();
    }
}

PHP API reference

CountryProvider

class TYPO3\CMS\Core\Country\CountryProvider

A class providing information about all countries.

Country data is generated from "Build/Scripts/updateIsoDatabase.php" (which in turn stems from https://github.com/sokil/php-isocodes-db-i18n)

getAll()
Return type

array

Returns

Country[]

getByIsoCode(string $isoCode)
Parameters
  • $isoCode (string) -- the isoCode

Return type

TYPO3\CMS\Core\Country\Country

getByAlpha2IsoCode(string $isoCode)
Parameters
  • $isoCode (string) -- the isoCode

Return type

TYPO3\CMS\Core\Country\Country

getByAlpha3IsoCode(string $isoCode)
Parameters
  • $isoCode (string) -- the isoCode

Return type

TYPO3\CMS\Core\Country\Country

getByEnglishName(string $name)
Parameters
  • $name (string) -- the name

Return type

TYPO3\CMS\Core\Country\Country

getFiltered(TYPO3\\CMS\\Core\\Country\\CountryFilter $filter)
Parameters
Return type

array

Returns

array<string,Country>

CountryFilter

class TYPO3\CMS\Core\Country\CountryFilter

Filter object to limit countries to a subset of all countries.

getExcludeCountries()
Return type

array

setExcludeCountries(array $excludeCountries)
Parameters
  • $excludeCountries (array) -- the excludeCountries

Return type

TYPO3\CMS\Core\Country\CountryFilter

getOnlyCountries()
Return type

array

setOnlyCountries(array $onlyCountries)
Parameters
  • $onlyCountries (array) -- the onlyCountries

Return type

TYPO3\CMS\Core\Country\CountryFilter

Country

class TYPO3\CMS\Core\Country\Country

DTO that keeps the information about a country. Never instantiate directly, use CountryProvider instead.

getName()
Return type

string

getLocalizedNameLabel()
Return type

string

getOfficialName()
Return type

string

getLocalizedOfficialNameLabel()
Return type

string

getAlpha2IsoCode()
Return type

string

getAlpha3IsoCode()
Return type

string

getNumericRepresentation()
Return type

string

getFlag()
Return type

string

Form ViewHelper

A Fluid ViewHelper is shipped with TYPO3 to render a dropdown for forms. See f:form.countrySelect for more information.