Address::getCountry() + normalize Country fields to Country models

CHANGELOG-WIP.md

@@ -18,10 +18,12 @@
 - The `allowedGraphqlOrigins` config setting is now deprecated. `craft\filters\Cors` should be used instead. ([#15397](https://github.com/craftcms/cms/pull/15397))
 - The `permissionsPolicyHeader` config settings is now deprecated. `craft\filters\Headers` should be used instead. ([#15397](https://github.com/craftcms/cms/pull/15397))
 - `{% cache %}` tags now cache any asset bundles registered within them.
+- Country field values are now set to `CommerceGuys\Addressing\Country\Country` objects. ([#15463](https://github.com/craftcms/cms/pull/15463))
 - Auto-populated section and category group Template settings are now suffixed with `.twig`.
 
 ### Extensibility
 - Added `craft\config\GeneralConfig::addAlias()`. ([#15346](https://github.com/craftcms/cms/pull/15346))
+- Added `craft\elements\Address::getCountry()`. ([#15463](https://github.com/craftcms/cms/pull/15463))
 - Added `craft\elements\Asset::$sanitizeOnUpload`. ([#15430](https://github.com/craftcms/cms/discussions/15430))
 - Added `craft\filters\Cors`. ([#15397](https://github.com/craftcms/cms/pull/15397))
 - Added `craft\filters\Headers`. ([#15397](https://github.com/craftcms/cms/pull/15397))

src/elements/Address.php

@@ -4,6 +4,7 @@
 
 use CommerceGuys\Addressing\AddressFormat\AddressField;
 use CommerceGuys\Addressing\AddressInterface;
+use CommerceGuys\Addressing\Country\Country;
 use Craft;
 use craft\base\BlockElementInterface;
 use craft\base\Element;
@@ -407,6 +408,17 @@ public function getCountryCode(): string
         return $this->countryCode;
     }
 
+    /**
+     * Returns a [[Country]] object representing the address’ coutry.
+     *
+     * @return Country
+     * @since 4.11.0
+     */
+    public function getCountry(): Country
+    {
+        return Craft::$app->getAddresses()->getCountryRepository()->get($this->countryCode);
+    }
+
     /**
      * @inheritdoc
      */

src/fields/Country.php

@@ -7,6 +7,8 @@
 
 namespace craft\fields;
 
+use CommerceGuys\Addressing\Country\Country as CountryModel;
+use CommerceGuys\Addressing\Exception\UnknownCountryException;
 use Craft;
 use craft\base\ElementInterface;
 use craft\base\Field;
@@ -43,7 +45,19 @@ public static function valueType(): string
      */
     public function normalizeValue(mixed $value, ElementInterface $element = null): mixed
     {
-        return !in_array(strtolower($value), ['', '__blank__']) ? $value : null;
+        if ($value instanceof CountryModel) {
+            return $value;
+        }
+
+        if (!$value || strtolower($value) === '__blank__') {
+            return null;
+        }
+
+        try {
+            return Craft::$app->getAddresses()->getCountryRepository()->get($value);
+        } catch (UnknownCountryException) {
+            return null;
+        }
     }
 
     /**
@@ -62,6 +76,15 @@ protected function inputHtml(mixed $value, ?ElementInterface $element = null): s
         ]);
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function serializeValue(mixed $value, ?ElementInterface $element = null): mixed
+    {
+        /** @var CountryModel|null $value */
+        return $value?->getCountryCode();
+    }
+
     /**
      * @inheritdoc
      */