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.

Contents

Using the PHP API
PHP API reference
Form ViewHelper

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

$filter (TYPO3\CMS\Core\Country\CountryFilter) -- the filter

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.