feat: added Country rule

Author: andrepimpao

composer.json

@@ -13,6 +13,7 @@
     ],
     "require": {
         "php": ">=8.1",
+        "symfony/intl": "^6.3",
         "symfony/polyfill-ctype": "^1.27"
     },
     "require-dev": {

src/Exception/CountryException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Exception;
+
+class CountryException extends ValidationException {}

src/Rule/Country.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\CountryException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use Symfony\Component\Intl\Countries;
+
+class Country extends AbstractRule implements RuleInterface
+{
+    public const ALPHA2_CODE = 'alpha2';
+    public const ALPHA3_CODE = 'alpha3';
+
+    private const CODE_OPTIONS = [
+        self::ALPHA2_CODE,
+        self::ALPHA3_CODE
+    ];
+
+    public function __construct(
+        private readonly string $code = self::ALPHA2_CODE,
+        private readonly string $message = 'The "{{ name }}" value is not a valid "{{ code }}" country code, "{{ value }}" given.'
+    ) {}
+
+    public function assert(mixed $value, string $name): void
+    {
+        if (!\in_array($this->code, self::CODE_OPTIONS)) {
+            throw new UnexpectedValueException(
+                \sprintf(
+                    'Invalid code "%s". Accepted values are: "%s".',
+                    $this->code,
+                    \implode(", ", self::CODE_OPTIONS)
+                )
+            );
+        }
+
+        if (!\is_string($value)) {
+            throw new UnexpectedValueException(
+                \sprintf('Expected value of type "string", "%s" given.', get_debug_type($value))
+            );
+        }
+
+        // Keep original value for parameters
+        $input = strtoupper($value);
+
+        if (
+            ($this->code === self::ALPHA2_CODE && !Countries::exists($input))
+            || ($this->code === self::ALPHA3_CODE && !Countries::alpha3CodeExists($input))
+        ) {
+            throw new CountryException(
+                message: $this->message,
+                parameters: [
+                    'name' => $name,
+                    'value' => $value,
+                    'code' => $this->code
+                ]
+            );
+        }
+    }
+}

tests/CountryTest.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Test;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\CountryException;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\Country;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleUnexpectedValueTrait;
+
+class CountryTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        $codeMessage = '/Invalid code "(.*)". Accepted values are: "(.*)"./';
+        $typeMessage = '/Expected value of type "string", "(.*)" given./';
+
+        yield 'invalid code' => [new Country('invalid'), 'PT', $codeMessage];
+        yield 'invalid type' => [new Country(), 123, $typeMessage];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $exception = CountryException::class;
+        $message = '/The "(.*)" value is not a valid "(.*)" country code, "(.*)" given./';
+
+        yield 'default' => [new Country(), 'PRT', $exception, $message];
+        yield 'alpha2' => [new Country(code: 'alpha2'), 'PRT', $exception, $message];
+        yield 'alpha3' => [new Country(code: 'alpha3'), 'PT', $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'default' => [new Country(), 'PT'];
+        yield 'alpha2' => [new Country(code: 'alpha2'), 'PT'];
+        yield 'alpha2 lowercase' => [new Country(code: 'alpha2'), 'pt'];
+        yield 'alpha3' => [new Country(code: 'alpha3'), 'PRT'];
+        yield 'alpha3 lowercase' => [new Country(code: 'alpha3'), 'prt'];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new Country(
+                message: 'The "{{ name }}" value "{{ value }}" is not a valid "{{ code }}" country code.'
+            ),
+            'invalid',
+            'The "test" value "invalid" is not a valid "alpha2" country code.'
+        ];
+    }
+}