---
title: "Country API"
manual: "TYPO3 Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3coreapi:country-api@13.4"
source: "ApiOverview/Country/Index.rst"
rendered: "2026-09-23T17:02:48+00:00"
---

# Country API {#country-api}

<!-- TODO: no Markdown rendering for "versionadded" -->

TYPO3 ships a list of countries of the world. The list is based on the
[ISO 3166-1](https://en.wikipedia.org/wiki/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](https://salsa.debian.org/iso-codes-team/iso-codes) and shipped
> statically as PHP content in the Country API.

**Contents**

-   [Using the PHP API](https://docs.typo3.org/permalink/t3coreapi:using-the-php-api@13.4)
-   [PHP API reference](https://docs.typo3.org/permalink/t3coreapi:php-api-reference@13.4)
-   [Form ViewHelper](https://docs.typo3.org/permalink/t3coreapi:form-viewhelper@13.4)

## Using the PHP API {#country-api-php-api}

[Dependency injection](https://docs.typo3.org/permalink/t3coreapi:dependencyinjection@13.4) can be used to retrieve the
`\TYPO3\CMS\Core\Country\CountryProvider` class:

**EXT:my_extension/Classes/MyClass.php**

```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 {#country-api-php-api-get-countries}

To get all countries call the `getAll()` method:

**EXT:my_extension/Classes/MyClass.php**

```php
$allCountries = $this->countryProvider->getAll();
```

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

### Get a country {#country-api-php-api-get-country}

**EXT:my_extension/Classes/MyClass.php**

```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 {#country-api-php-api-filter-countries}

One can use filters to get the desired countries:

**EXT:my_extension/Classes/MyClass.php**

```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 {#country-api-php-api-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
<?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 {#country-api-php-api-reference}

### `CountryProvider` {#country-api-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](https://github.com/sokil/php-isocodes-db-i18n))

    -   **getAll()**

        *Returns:* `Country[]`

    -   **getByIsoCode(string $isoCode)**

        -   *param $isoCode:* the isoCode

        *Returns:* `?TYPO3CMSCoreCountryCountry`

    -   **getByAlpha2IsoCode(string $isoCode)**

        -   *param $isoCode:* the isoCode

        *Returns:* `?TYPO3CMSCoreCountryCountry`

    -   **getByAlpha3IsoCode(string $isoCode)**

        -   *param $isoCode:* the isoCode

        *Returns:* `?TYPO3CMSCoreCountryCountry`

    -   **getByEnglishName(string $name)**

        -   *param $name:* the name

        *Returns:* `?TYPO3CMSCoreCountryCountry`

    -   **getFiltered(\\TYPO3\\CMS\\Core\\Country\\CountryFilter $filter)**

        -   *param $filter:* the filter

        *Returns:* `array<string,Country>`

### `CountryFilter` {#country-api-php-api-reference-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` {#country-api-php-api-reference-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 {#country-select-viewhelper}

A Fluid ViewHelper is shipped with TYPO3 to render a dropdown for forms. See
[f:form.countrySelect](https://docs.typo3.org/other/typo3/view-helper-reference/13.4/en-us/Global/Form/CountrySelect.html#typo3-fluid-form-countryselect) for
more information.