[FEATURE] #99618 - Add all countries and their localized names (#2620)

Resolves: TYPO3-Documentation/Changelog-To-Doc#324
Releases: main

Documentation/ApiOverview/Country/Index.rst

@@ -0,0 +1,101 @@
+..  include:: /Includes.rst.txt
+..  index:: Country API
+..  _country-api:
+
+===========
+Country API
+===========
+
+..  versionadded:: 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.
+
+..  _ISO 3166-1: https://en.wikipedia.org/wiki/ISO_3166-1
+..  _Debian's ISO code list: https://salsa.debian.org/iso-codes-team/iso-codes
+
+.. contents:: Contents
+   :local:
+
+
+Using the PHP API
+=================
+
+:ref:`Dependency injection <DependencyInjection>` can be used to retrieve the
+:php:`\TYPO3\CMS\Core\Country\CountryProvider` class:
+
+..  literalinclude:: _MyClass.php
+    :caption: EXT:my_extension/Classes/MyClass.php
+
+
+Get a country
+-------------
+
+..  code-block:: php
+    :caption: 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->getByName('France');
+
+    // Get the country by Alpha-3 code
+    $france = $this->$countryProvider->getByAlpha3IsoCode('FRA');
+
+The methods return a :php:`\TYPO3\CMS\Core\Country\Country` object.
+
+
+Get all countries
+-----------------
+
+To get all countries call the :php:`getAll()` method:
+
+..  code-block:: php
+    :caption: EXT:my_extension/Classes/MyClass.php
+
+    $allCountries = $this->countryProvider->getAll();
+
+The method returns an array of :php:`\TYPO3\CMS\Core\Country\Country` objects.
+
+
+The :php:`Country` object
+-------------------------
+
+A country object can be used to fetch all information about it, also with
+translatable labels:
+
+..  literalinclude:: _MyClassWithTranslation.php
+    :caption: EXT:my_extension/Classes/MyClassWithTranslation.php
+
+
+PHP API reference
+=================
+
+:php:`CountryProvider`
+----------------------
+
+.. include:: /CodeSnippets/Manual/Country/CountryProvider.rst.txt
+
+:php:`Country`
+--------------
+
+.. include:: /CodeSnippets/Manual/Country/Country.rst.txt
+
+
+..  index:: CountrySelect ViewHelper
+..  _country-select-viewhelper:
+
+Form ViewHelper
+===============
+
+A Fluid ViewHelper is shipped with TYPO3 to render a dropdown for forms. See
+:ref:`f:form.countrySelect <t3viewhelper:typo3-fluid-form-countryselect>` for
+more information.

Documentation/ApiOverview/Country/_MyClass.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension;
+
+use TYPO3\CMS\Core\Country\CountryProvider;
+
+final class MyClass
+{
+    public function __construct(
+        private readonly CountryProvider $countryProvider
+    ) {
+    }
+}

Documentation/ApiOverview/Country/_MyClassWithTranslation.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension;
+
+use TYPO3\CMS\Core\Country\CountryProvider;
+use TYPO3\CMS\Core\Localization\LanguageServiceFactory;
+
+final class MyClassWithTranslation
+{
+    public function __construct(
+        private readonly CountryProvider $countryProvider,
+        private readonly LanguageServiceFactory $languageServiceFactory
+    ) {
+    }
+
+    public function doSomething()
+    {
+        $languageService = $this->languageServiceFactory->create('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();
+    }
+}

Documentation/CodeSnippets/Config/Api/All.php

@@ -6,6 +6,7 @@
 return array_merge(
     include('Events/All.php'),
     include('BackendApi.php'),
+    include('CountryApi.php'),
     include('Entity.php'),
     include('LanguageServiceApi.php'),
     include('SessionManagement.php'),

Documentation/CodeSnippets/Config/Api/CountryApi.php

@@ -0,0 +1,16 @@
+<?php
+
+return [
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Core\Country\Country::class,
+        'targetFileName' => 'CodeSnippets/Manual/Country/Country.rst.txt',
+        'withCode' => false,
+    ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Core\Country\CountryProvider::class,
+        'targetFileName' => 'CodeSnippets/Manual/Country/CountryProvider.rst.txt',
+        'withCode' => false,
+    ],
+];

Documentation/CodeSnippets/Manual/Country/Country.rst.txt

@@ -0,0 +1,41 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets 
+.. php:namespace::  TYPO3\CMS\Core\Country
+
+.. php:class:: Country
+
+   DTO that keeps the information about a country. Never instantiate directly,
+   use CountryProvider instead.
+
+
+
+   .. php:method:: getName()
+   
+      :returntype: string
+
+   .. php:method:: getLocalizedNameLabel()
+   
+      :returntype: string
+
+   .. php:method:: getOfficialName()
+   
+      :returntype: string
+
+   .. php:method:: getLocalizedOfficialNameLabel()
+   
+      :returntype: string
+
+   .. php:method:: getAlpha2IsoCode()
+   
+      :returntype: string
+
+   .. php:method:: getAlpha3IsoCode()
+   
+      :returntype: string
+
+   .. php:method:: getNumericRepresentation()
+   
+      :returntype: string
+
+   .. php:method:: getFlag()
+   
+      :returntype: string

Documentation/CodeSnippets/Manual/Country/CountryProvider.rst.txt

@@ -0,0 +1,33 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets 
+.. php:namespace::  TYPO3\CMS\Core\Country
+
+.. php:class:: 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)
+
+
+   .. php:method:: getAll()
+   
+      :returntype: array
+
+   .. php:method:: getByIsoCode(string $isoCode)
+   
+      :param string $isoCode: the isoCode
+      :returntype: TYPO3\\CMS\\Core\\Country\\Country
+
+   .. php:method:: getByAlpha2IsoCode(string $isoCode)
+   
+      :param string $isoCode: the isoCode
+      :returntype: TYPO3\\CMS\\Core\\Country\\Country
+
+   .. php:method:: getByAlpha3IsoCode(string $isoCode)
+   
+      :param string $isoCode: the isoCode
+      :returntype: TYPO3\\CMS\\Core\\Country\\Country
+
+   .. php:method:: getByEnglishName(string $name)
+   
+      :param string $name: the name
+      :returntype: TYPO3\\CMS\\Core\\Country\\Country