Merge pull request #29 from programmatordev/YAPV-44-create-country-rule

Create 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": {

docs/03x-rules-choice.md

@@ -40,7 +40,7 @@ Validator::choice(['red', 'green', 'blue'], multiple: true, minConstraint: 2, ma
 ```
 
 > **Note**
-> An `UnexpectedValueException` will be thrown when `multiple` is `true` and value to be validated is not an `array`.
+> An `UnexpectedValueException` will be thrown when `multiple` is `true` and the input value is not an `array`.
 
 > **Note**
 > An `UnexpectedValueException` will be thrown when the `minConstraint` value is greater than or equal to the `maxConstraint` value.

docs/03x-rules-country.md

@@ -0,0 +1,55 @@
+# Country
+
+Validates that a value is a valid country code.
+
+```php
+Country(
+    string $code = 'alpha-2',
+    string $message = 'The "{{ name }}" value is not a valid country code, "{{ value }}" given.'
+);
+```
+
+## Basic Usage
+
+```php
+// Default alpha-2 code
+Validator::country()->validate('PT'); // true
+Validator::country(code: 'alpha-2')->validate('PT'); // true
+
+// Alpha-3 code
+Validator::country(code: 'alpha-3')->validate('PRT'); // true
+```
+
+> **Note**
+> An `UnexpectedValueException` will be thrown when the `code` value is not a valid option.
+
+> **Note**
+> An `UnexpectedValueException` will be thrown when the input value is not a `string`.
+
+## Options
+
+### `code`
+
+type: `string` default: `alpha-2`
+
+Set code type to validate the country. 
+Check the [official country codes](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) list for more information.
+
+Available options:
+
+- `alpha-2`: two-letter code
+- `alpha-3`: three-letter code
+
+### `message`
+
+type `string` default: `The "{{ name }}" value is not a valid country code, "{{ value }}" given.`
+
+Message that will be shown if the input value is not a valid country code.
+
+The following parameters are available:
+
+| Parameter     | Description               |
+|---------------|---------------------------|
+| `{{ value }}` | The current invalid value |
+| `{{ name }}`  | Name of the invalid value |
+| `{{ code }}`  | Selected code type        |

docs/03x-rules-type.md

@@ -9,17 +9,17 @@ For example, if `['alpha', 'numeric']` is provided, it will validate if the valu
 Type(
     string|array $constraint,
     string $message = 'The "{{ name }}" value should be of type "{{ constraint }}", "{{ value }}" given.'
-)
+);
 ```
 
 ## Basic Usage
 
 ```php
-// Single data type
+// Single type
 Validator::type('string')->validate('green'); // true
 Validator::type('alphanumeric')->validate('gr33n'); // true
 
-// Multiple data types
+// Multiple types
 // Validates if value is of at least one of the provided types
 Validator::type(['alpha', 'numeric'])->validate('green'); // true (alpha)
 Validator::type(['alpha', 'numeric'])->validate('33'); // true (numeric)
@@ -31,7 +31,7 @@ Validator::type(\DateTimeInterface::class)->validate(new \DateTime()); // true
 ```
 
 > **Note**
-> An `UnexpectedValueException` will be thrown when a constraint type, class and interface is invalid.
+> An `UnexpectedValueException` will be thrown when a constraint type, class or interface is invalid.
 
 ## Options
 
@@ -45,7 +45,7 @@ Can validate instances of classes and interfaces.
 If an array with multiple types is provided, it will validate if the value is of at least one of the given types.
 For example, if `['alpha', 'numeric']` is provided, it will validate if the value is of type `alpha` or of type `numeric`.
 
-Available constraint types:
+Available data type constraints:
 
 - [`bool`](https://www.php.net/manual/en/function.is-bool.php), [`boolean`](https://www.php.net/manual/en/function.is-bool.php)
 - [`int`](https://www.php.net/manual/en/function.is-int.php), [`integer`](https://www.php.net/manual/en/function.is-int.php), [`long`](https://www.php.net/manual/en/function.is-int.php)
@@ -60,6 +60,9 @@ Available constraint types:
 - [`object`](https://www.php.net/manual/en/function.is-object.php)
 - [`resource`](https://www.php.net/manual/en/function.is-resource.php)
 - [`null`](https://www.php.net/manual/en/function.is-null.php)
+
+Available character type constraints:
+
 - [`alphanumeric`](https://www.php.net/manual/en/function.ctype-alnum)
 - [`alpha`](https://www.php.net/manual/en/function.ctype-alpha.php)
 - [`digit`](https://www.php.net/manual/en/function.ctype-digit.php)

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 ALPHA_2_CODE = 'alpha-2';
+    public const ALPHA_3_CODE = 'alpha-3';
+
+    private const CODE_OPTIONS = [
+        self::ALPHA_2_CODE,
+        self::ALPHA_3_CODE
+    ];
+
+    public function __construct(
+        private readonly string $code = self::ALPHA_2_CODE,
+        private readonly string $message = 'The "{{ name }}" value is not a valid 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::ALPHA_2_CODE && !Countries::exists($input))
+            || ($this->code === self::ALPHA_3_CODE && !Countries::alpha3CodeExists($input))
+        ) {
+            throw new CountryException(
+                message: $this->message,
+                parameters: [
+                    'name' => $name,
+                    'value' => $value,
+                    'code' => $this->code
+                ]
+            );
+        }
+    }
+}

src/Rule/Type.php

@@ -7,36 +7,66 @@
 
 class Type extends AbstractRule implements RuleInterface
 {
+    public const BOOL = 'bool';
+    public const BOOLEAN = 'boolean';
+    public const INT = 'int';
+    public const INTEGER = 'integer';
+    public const LONG = 'long';
+    public const FLOAT = 'float';
+    public const DOUBLE = 'double';
+    public const REAL = 'real';
+    public const NUMERIC = 'numeric';
+    public const STRING = 'string';
+    public const SCALAR = 'scalar';
+    public const ARRAY = 'array';
+    public const ITERABLE = 'iterable';
+    public const COUNTABLE = 'countable';
+    public const CALLABLE = 'callable';
+    public const OBJECT = 'object';
+    public const RESOURCE = 'resource';
+    public const NULL = 'null';
+    public const ALPHANUMERIC = 'alphanumeric';
+    public const ALPHA = 'alpha';
+    public const DIGIT = 'digit';
+    public const CONTROL = 'control';
+    public const PUNCTUATION = 'punctuation';
+    public const HEXADECIMAL = 'hexadecimal';
+    public const GRAPH = 'graph';
+    public const PRINTABLE = 'printable';
+    public const WHITESPACE = 'whitespace';
+    public const LOWERCASE = 'lowercase';
+    public const UPPERCASE = 'uppercase';
+
     private const TYPE_FUNCTIONS = [
-        'bool' => 'is_bool',
-        'boolean' => 'is_bool',
-        'int' => 'is_int',
-        'integer' => 'is_int',
-        'long' => 'is_int',
-        'float' => 'is_float',
-        'double' => 'is_float',
-        'real' => 'is_float',
-        'numeric' => 'is_numeric',
-        'string' => 'is_string',
-        'scalar' => 'is_scalar',
-        'array' => 'is_array',
-        'iterable' => 'is_iterable',
-        'countable' => 'is_countable',
-        'callable' => 'is_callable',
-        'object' => 'is_object',
-        'resource' => 'is_resource',
-        'null' => 'is_null',
-        'alphanumeric' => 'ctype_alnum',
-        'alpha' => 'ctype_alpha',
-        'digit' => 'ctype_digit',
-        'control' => 'ctype_cntrl',
-        'punctuation' => 'ctype_punct',
-        'hexadecimal' => 'ctype_xdigit',
-        'graph' => 'ctype_graph',
-        'printable' => 'ctype_print',
-        'whitespace' => 'ctype_space',
-        'lowercase' => 'ctype_lower',
-        'uppercase' => 'ctype_upper'
+        self::BOOL => 'is_bool',
+        self::BOOLEAN => 'is_bool',
+        self::INT => 'is_int',
+        self::INTEGER => 'is_int',
+        self::LONG => 'is_int',
+        self::FLOAT => 'is_float',
+        self::DOUBLE => 'is_float',
+        self::REAL => 'is_float',
+        self::NUMERIC => 'is_numeric',
+        self::STRING => 'is_string',
+        self::SCALAR => 'is_scalar',
+        self::ARRAY => 'is_array',
+        self::ITERABLE => 'is_iterable',
+        self::COUNTABLE => 'is_countable',
+        self::CALLABLE => 'is_callable',
+        self::OBJECT => 'is_object',
+        self::RESOURCE => 'is_resource',
+        self::NULL => 'is_null',
+        self::ALPHANUMERIC => 'ctype_alnum',
+        self::ALPHA => 'ctype_alpha',
+        self::DIGIT => 'ctype_digit',
+        self::CONTROL => 'ctype_cntrl',
+        self::PUNCTUATION => 'ctype_punct',
+        self::HEXADECIMAL => 'ctype_xdigit',
+        self::GRAPH => 'ctype_graph',
+        self::PRINTABLE => 'ctype_print',
+        self::WHITESPACE => 'ctype_space',
+        self::LOWERCASE => 'ctype_lower',
+        self::UPPERCASE => 'ctype_upper'
     ];
 
     public function __construct(
@@ -57,12 +87,12 @@ public function assert(mixed $value, string $name): void
                 return;
             }
 
-            if (!isset(self::TYPE_FUNCTIONS[$constraint]) && !class_exists($constraint) && !interface_exists($constraint)) {
+            if (!isset(self::TYPE_FUNCTIONS[$constraint]) && !\class_exists($constraint) && !\interface_exists($constraint)) {
                 throw new UnexpectedValueException(
                     \sprintf(
                         'Invalid constraint type "%s". Accepted values are: "%s"',
                         $constraint,
-                        implode(', ', array_keys(self::TYPE_FUNCTIONS))
+                        \implode('", "', \array_keys(self::TYPE_FUNCTIONS))
                     )
                 );
             }

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: 'alpha-2'), 'PRT', $exception, $message];
+        yield 'alpha3' => [new Country(code: 'alpha-3'), 'PT', $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'default' => [new Country(), 'PT'];
+        yield 'alpha2' => [new Country(code: 'alpha-2'), 'PT'];
+        yield 'alpha2 lowercase' => [new Country(code: 'alpha-2'), 'pt'];
+        yield 'alpha3' => [new Country(code: 'alpha-3'), 'PRT'];
+        yield 'alpha3 lowercase' => [new Country(code: 'alpha-3'), '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 "alpha-2" country code.'
+        ];
+    }
+}

tests/NotBlankTest.php

@@ -17,15 +17,15 @@ class NotBlankTest extends AbstractTest
     public static function provideRuleFailureConditionData(): \Generator
     {
         $exception = NotBlankException::class;
-        $exceptionMessage = '/The "(.*)" value should not be blank, "(.*)" given./';
+        $message = '/The "(.*)" value should not be blank, "(.*)" given./';
 
-        yield 'null' => [new NotBlank(), null, $exception, $exceptionMessage];
-        yield 'false' => [new NotBlank(), false, $exception, $exceptionMessage];
-        yield 'blank string' => [new NotBlank(), '', $exception, $exceptionMessage];
-        yield 'blank array' => [new NotBlank(), [], $exception, $exceptionMessage];
+        yield 'null' => [new NotBlank(), null, $exception, $message];
+        yield 'false' => [new NotBlank(), false, $exception, $message];
+        yield 'blank string' => [new NotBlank(), '', $exception, $message];
+        yield 'blank array' => [new NotBlank(), [], $exception, $message];
 
-        yield 'normalizer whitespace' => [new NotBlank(normalizer: 'trim'), ' ', $exception, $exceptionMessage];
-        yield 'normalizer whitespace function' => [new NotBlank(normalizer: fn($value) => trim($value)), ' ', $exception, $exceptionMessage];
+        yield 'normalizer whitespace' => [new NotBlank(normalizer: 'trim'), ' ', $exception, $message];
+        yield 'normalizer whitespace function' => [new NotBlank(normalizer: fn($value) => trim($value)), ' ', $exception, $message];
     }
 
     public static function provideRuleSuccessConditionData(): \Generator