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¶
Dependency injection can be used to retrieve the
\TYPO3\CMS\Core\Country\CountryProvider
class:
<?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:
$allCountries = $this->countryProvider->getAll();
The method returns an array of \TYPO3\CMS\Core\Country\Country
objects.
Get a country¶
// 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:
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:
<?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
- getByAlpha2IsoCode(string $isoCode)¶
- Parameters
$isoCode (
string
) -- the isoCode
- Return type
- getByAlpha3IsoCode(string $isoCode)¶
- Parameters
$isoCode (
string
) -- the isoCode
- Return type
- getByEnglishName(string $name)¶
- Parameters
$name (
string
) -- the name
- Return type
- 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
- getOnlyCountries()¶
- Return type
array
- setOnlyCountries(array $onlyCountries)¶
- Parameters
$onlyCountries (
array
) -- the onlyCountries
- Return type
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.