Merge pull request #15711 from craftcms/feature/add-get-country-list-…

…method-for-addresses

[4.x] Ability to limit the countries available for selection when editing an address

CHANGELOG-WIP.md

@@ -2,9 +2,12 @@
 
 ### Extensibility
 - Added `craft\base\RequestTrait::getIsWebRequest()`. ([#15690](https://github.com/craftcms/cms/pull/15690))
+- Added `craft\events\DefineAddressCountriesEvent`. ([#15711](https://github.com/craftcms/cms/pull/15711))
 - Added `craft\filters\BasicHttpAuthLogin`. ([#15720](https://github.com/craftcms/cms/pull/15720))
 - Added `craft\filters\BasicHttpAuthStatic`. ([#15720](https://github.com/craftcms/cms/pull/15720))
 - Added `craft\filters\SiteFilterTrait::$enabled`. ([#15720](https://github.com/craftcms/cms/pull/15720))
+- Added `craft\services\Addresses::EVENT_DEFINE_ADDRESS_COUNTRIES`. ([#15711](https://github.com/craftcms/cms/pull/15711))
+- Added `craft\services\Addresses::getCountryList()`. ([#15711](https://github.com/craftcms/cms/pull/15711))
 - Added `craft\web\View::registerCpTwigExtension()`.
 - Added `craft\web\View::registerSiteTwigExtension()`.
 - Deprecated the `enableBasicHttpAuth` config setting. `craft\filters\BasicHttpAuthLogin` should be used instead. ([#15720](https://github.com/craftcms/cms/pull/15720))

src/elements/conditions/addresses/AdministrativeAreaConditionRule.php

@@ -101,7 +101,7 @@ protected function inputHtml(): string
         $countrySelect = Cp::selectFieldHtml([
             'id' => 'country-code',
             'name' => 'countryCode',
-            'options' => Craft::$app->getAddresses()->getCountryRepository()->getList(),
+            'options' => Craft::$app->getAddresses()->getCountryList(),
             'value' => $this->countryCode,
             'inputAttributes' => [
                 'hx' => [

src/elements/conditions/addresses/CountryConditionRule.php

@@ -39,7 +39,7 @@ public function getExclusiveQueryParams(): array
      */
     protected function options(): array
     {
-        return Craft::$app->getAddresses()->getCountryRepository()->getList();
+        return Craft::$app->getAddresses()->getCountryList();
     }
 
     /**

src/events/DefineAddressCountriesEvent.php

@@ -0,0 +1,29 @@
+<?php
+/**
+ * @link https://craftcms.com/
+ * @copyright Copyright (c) Pixel & Tonic, Inc.
+ * @license https://craftcms.github.io/license/
+ */
+
+namespace craft\events;
+
+use craft\base\Event;
+
+/**
+ * DefineAddressCountriesEvent event class.
+ *
+ * @author Pixel & Tonic, Inc. <[email protected]>
+ * @since 4.13.0
+ */
+class DefineAddressCountriesEvent extends Event
+{
+    /**
+     * @var string $locale
+     */
+    public string $locale;
+
+    /**
+     * @var array list of countries keyed by their country code.
+     */
+    public array $countries;
+}

src/fieldlayoutelements/addresses/CountryCodeField.php

@@ -94,7 +94,7 @@ protected function inputHtml(?ElementInterface $element = null, bool $static = f
             Cp::selectizeHtml([
                 'id' => 'countryCode',
                 'name' => 'countryCode',
-                'options' => Craft::$app->getAddresses()->getCountryRepository()->getList(Craft::$app->language),
+                'options' => Craft::$app->getAddresses()->getCountryList(Craft::$app->language),
                 'value' => $element->countryCode,
                 'autocomplete' => $element->getBelongsToCurrentUser() ? 'country' : 'off',
             ]) .

src/fields/Country.php

@@ -65,7 +65,7 @@ public function normalizeValue(mixed $value, ElementInterface $element = null):
      */
     protected function inputHtml(mixed $value, ?ElementInterface $element = null): string
     {
-        $options = Craft::$app->getAddresses()->getCountryRepository()->getList(Craft::$app->language);
+        $options = Craft::$app->getAddresses()->getCountryList(Craft::$app->language);
         array_unshift($options, ['label' => ' ', 'value' => '__blank__']);
 
         return Cp::selectizeHtml([

src/fields/conditions/CountryFieldConditionRule.php

@@ -17,7 +17,7 @@ class CountryFieldConditionRule extends BaseMultiSelectConditionRule implements
 
     protected function options(): array
     {
-        return Craft::$app->getAddresses()->getCountryRepository()->getList(Craft::$app->language);
+        return Craft::$app->getAddresses()->getCountryList(Craft::$app->language);
     }
 
     /**

src/services/Addresses.php

@@ -20,6 +20,7 @@
 use craft\addresses\SubdivisionRepository;
 use craft\elements\Address;
 use craft\events\ConfigEvent;
+use craft\events\DefineAddressCountriesEvent;
 use craft\events\DefineAddressFieldLabelEvent;
 use craft\events\DefineAddressFieldsEvent;
 use craft\events\DefineAddressSubdivisionsEvent;
@@ -69,6 +70,18 @@ class Addresses extends Component
      */
     public const EVENT_DEFINE_ADDRESS_SUBDIVISIONS = 'defineAddressSubdivisions';
 
+    /**
+     * @event DefineAddressCountriesEvent The event that is triggered when defining country options for an address.
+     *
+     * This event is primarily used to modify the list of countries that are available for selection. You can also use
+     * the event to add additional countries to the list, however, this will require you to use dependency injection to override the
+     * `Addresses::getCountryRepository()` method and provide your own `CountryRepository` instance.
+     *
+     * @see getCountryList()
+     * @since 4.13.0
+     */
+    public const EVENT_DEFINE_ADDRESS_COUNTRIES = 'defineAddressCountries';
+
     /**
      * @var FormatterInterface|null The default address formatter used by [[formatAddress()]]
      * @since 4.5.0
@@ -155,6 +168,31 @@ public function defineAddressSubdivisions(array $parents, array $options = []):
         return $options;
     }
 
+    /**
+     * Returns a list of countries to be used as options for selection.
+     *
+     * @param string|null $locale
+     * @return array
+     * @since 4.13.0
+     */
+    public function getCountryList(?string $locale = null): array
+    {
+        $locale ??= Craft::$app->language;
+        $countries = $this->getCountryRepository()->getList($locale);
+
+        if ($this->hasEventHandlers(self::EVENT_DEFINE_ADDRESS_COUNTRIES)) {
+            $event = new DefineAddressCountriesEvent([
+                'locale' => $locale,
+                'countries' => $countries,
+            ]);
+            $this->trigger(self::EVENT_DEFINE_ADDRESS_COUNTRIES, $event);
+
+            return $event->countries;
+        }
+
+        return $countries;
+    }
+
     /**
      * Returns the address fields that are used by a given country code.
      *