Developer Corner

Modification of the country list

It is possible to change the list of options in the country selection box with the PSR-14 event \Brotkrueml\FormCountrySelect\Event\CountriesModificationEvent This may be the case if you want to reduce the number of countries, change the order of the countries or perhaps add some "unofficial" countries.

The event provides the following methods:

->getFormIdentifier(): string

Get the form identifier (e.g. contact-42, where contact is the identifier and 42 the content element id).

->getCountries(): array

Returns the list of countries in the format:

[
   'DE' => 'Germany',
   'US' => 'United States',
   // ...
]

Copied!

->getLanguageTwoLetterIsoCode(): string

New in version 1.2.0

Get the two letter ISO code of the language of the page (e.g. en for English or de for German).

->setCountries(array $countries): void

Sets the countries in the same format as above.

Example

So, let's start with an example. Imagine that you want to display the most common English-speaking countries at the top of the option list.

1. Create the event listener

   EXT:your_extension/Classes/EventListener/ModifyCountryOrder.php

   <?php
   declare(strict_types=1);
   
   namespace YourVendor\YourExtension\EventListener;
   
   use Brotkrueml\FormCountrySelect\Event\CountriesModificationEvent;
   
   final class ModifyCountryOrder
   {
      private $mostCommonEnglishSpeakingCountries = ['AU', 'CA', 'NZ', 'GB', 'US'];
   
      public function __invoke(CountriesModificationEvent $event): void
      {
         $countries = $event->getCountries();
   
         $topCountries = [];
         foreach ($this->mostCommonEnglishSpeakingCountries as $country) {
            $topCountries[$country] = $countries[$country];
            unset($countries[$country]);
         }
   
         $event->setCountries(array_merge($topCountries, $countries));
      }
   }

   Copied!

   The method __invoke() implements the logic for changing the order of the countries. It receives the CountriesModificationEvent where you can get the countries. After your changes you have to assign the new country list with a call to the event method setCountries().

2. Register your event listener

   EXT:your_extension/Configuration/Services.yaml

   services:
      YourVendor\YourExtension\EventListener\ModifyCountryOrder:
         tags:
            - name: event.listener
              identifier: 'ext-yourextension/modifyCountryOrder'
              event: Brotkrueml\FormCountrySelect\Event\CountriesModificationEvent

   Copied!

See also

You can find more information in the blog article PSR-14 Events in TYPO3 and the official TYPO3 documentation.

Country list usage in other scenarios

It might be helpful to use the country list in other scenarios, e.g. an Extbase form – especially if a PSR-14 event has been assigned. For this case a CountryService class is available

use Brotkrueml\FormCountrySelect\Service\CountryService;

$countries = (new CountryService())->getCountries('de', 'some-identifier');

As already mentioned, the assigned PSR-14 events are taken into account. The ->getCountries() method has two optional arguments:

string $languageTwoLetterIsoCode

The ISO 3166-1 code of the language (e.g. de for German). Default: en.

string $identifier

The identifier is – well – an identifier. It is passed on to the event used by PSR-14 events, where you can work with the country list dependent on this identifier. Default: empty string.