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).

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,
    ) {}
}
Copied!

Get all countries

To get all countries call the getAll() method:

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

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');
Copied!

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);
Copied!

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();
    }
}
Copied!

PHP API reference

CountryProvider

class CountryProvider
Fully qualified name
\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 ( )
Returns
\Country[]
getByIsoCode ( string $isoCode)
param $isoCode

the isoCode

Returns
?\TYPO3\CMS\Core\Country\Country
getByAlpha2IsoCode ( string $isoCode)
param $isoCode

the isoCode

Returns
?\TYPO3\CMS\Core\Country\Country
getByAlpha3IsoCode ( string $isoCode)
param $isoCode

the isoCode

Returns
?\TYPO3\CMS\Core\Country\Country
getByEnglishName ( string $name)
param $name

the name

Returns
?\TYPO3\CMS\Core\Country\Country
getFiltered ( \TYPO3\CMS\Core\Country\CountryFilter $filter)
param $filter

the filter

Returns
array<string,\Country>

CountryFilter

class CountryFilter
Fully qualified name
\TYPO3\CMS\Core\Country\CountryFilter

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

getExcludeCountries ( )
returntype

array

setExcludeCountries ( array $excludeCountries)
param array $excludeCountries

the excludeCountries

returntype

TYPO3\CMS\Core\Country\CountryFilter

getOnlyCountries ( )
returntype

array

setOnlyCountries ( array $onlyCountries)
param array $onlyCountries

the onlyCountries

returntype

TYPO3\CMS\Core\Country\CountryFilter

Country

class Country
Fully qualified name
\TYPO3\CMS\Core\Country\Country

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

getName ( )
Returns
string
getLocalizedNameLabel ( )
Returns
string
getOfficialName ( )
Returns
?string
getLocalizedOfficialNameLabel ( )
Returns
string
getAlpha2IsoCode ( )
Returns
string
getAlpha3IsoCode ( )
Returns
string
getNumericRepresentation ( )
Returns
string
getFlag ( )
Returns
string

Form ViewHelper

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