Merge pull request #64 from programmatordev/YAPV-46-create-language-rule

Create Language rule

docs/03-rules.md

@@ -39,6 +39,7 @@
 
 - [Choice](03-rules_choice.md)
 - [Country](03-rules_country.md)
+- [Language](03-rules_language.md)
 
 ## Iterable Rules
 

docs/03-rules_country.md

@@ -41,7 +41,7 @@ Available options:
 
 ### `message`
 
-type: `?string` default: `The {{ name }} value is not a valid {{ code }} country code, {{ value }} given.`
+type: `?string` default: `The {{ name }} value is not a valid country, {{ value }} given.`
 
 Message that will be shown if the input value is not a valid country code.
 

docs/03-rules_language.md

@@ -0,0 +1,58 @@
+# Language
+
+Validates that a value is a valid language code.
+
+```php
+Language(
+    string $code = 'alpha-2',
+    ?string $message = null
+);
+```
+
+## Basic Usage
+
+```php
+// default alpha-2 code
+Validator::language()->validate('pt'); // true
+
+// alpha-3 code
+Validator::language(code: 'alpha-3')->validate('por'); // 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 language. 
+Check the [official language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_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 language, {{ value }} given.`
+
+Message that will be shown if the input value is not a valid language code.
+
+The following parameters are available:
+
+| Parameter     | Description               |
+|---------------|---------------------------|
+| `{{ value }}` | The current invalid value |
+| `{{ name }}`  | Name of the invalid value |
+| `{{ code }}`  | Selected code type        |
+
+## Changelog
+
+- `1.1.0` Created

src/ChainedValidatorInterface.php

@@ -70,6 +70,11 @@ public function greaterThanOrEqual(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public function language(
+        string $code = 'alpha-2',
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public function length(
         ?int $min = null,
         ?int $max = null,

src/Exception/LanguageException.php

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

src/Rule/Country.php

@@ -17,7 +17,7 @@ class Country extends AbstractRule implements RuleInterface
         self::ALPHA_3_CODE
     ];
 
-    private string $message = 'The {{ name }} value is not a valid {{ code }} country code, {{ value }} given.';
+    private string $message = 'The {{ name }} value is not a valid country, {{ value }} given.';
 
     public function __construct(
         private readonly string $code = self::ALPHA_2_CODE,
@@ -37,8 +37,8 @@ public function assert(mixed $value, ?string $name = null): void
             throw new UnexpectedTypeException('string', get_debug_type($value));
         }
 
-        // Keep original value for parameters
-        $input = strtoupper($value);
+        // keep original value for parameters
+        $input = \strtoupper($value);
 
         if (
             ($this->code === self::ALPHA_2_CODE && !Countries::exists($input))

src/Rule/Language.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Rule;
+
+use ProgrammatorDev\Validator\Exception\LanguageException;
+use ProgrammatorDev\Validator\Exception\UnexpectedOptionException;
+use ProgrammatorDev\Validator\Exception\UnexpectedTypeException;
+use Symfony\Component\Intl\Languages;
+
+class Language 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
+    ];
+
+    private string $message = 'The {{ name }} value is not a valid language, {{ value }} given.';
+
+    public function __construct(
+        private readonly string $code = self::ALPHA_2_CODE,
+        ?string $message = null
+    )
+    {
+        $this->message = $message ?? $this->message;
+    }
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        if (!\in_array($this->code, self::CODE_OPTIONS)) {
+            throw new UnexpectedOptionException('code', self::CODE_OPTIONS, $this->code);
+        }
+
+        if (!\is_string($value)) {
+            throw new UnexpectedTypeException('string', get_debug_type($value));
+        }
+
+        // keep original value for parameters
+        $input = \strtolower($value);
+
+        if (
+            ($this->code === self::ALPHA_2_CODE && !Languages::exists($input))
+            || ($this->code === self::ALPHA_3_CODE && !Languages::alpha3CodeExists($input))
+        ) {
+            throw new LanguageException(
+                message: $this->message,
+                parameters: [
+                    'name' => $name,
+                    'value' => $value,
+                    'code' => $this->code
+                ]
+            );
+        }
+    }
+}

src/StaticValidatorInterface.php

@@ -69,6 +69,11 @@ public static function greaterThanOrEqual(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public static function language(
+        string $code = 'alpha-2',
+        ?string $message = null
+    ): ChainedValidatorInterface&Validator;
+
     public static function length(
         ?int $min = null,
         ?int $max = null,

tests/CountryTest.php

@@ -21,27 +21,25 @@ public static function provideRuleUnexpectedValueData(): \Generator
         $unexpectedCodeMessage = '/Invalid code "(.*)"\. Accepted values are\: "(.*)"\./';
         $unexpectedTypeMessage = '/Expected value of type "string", (.*) given\./';
 
-        yield 'invalid code' => [new Country('invalid'), 'PT', $unexpectedCodeMessage];
+        yield 'invalid code' => [new Country('invalid'), 'pt', $unexpectedCodeMessage];
         yield 'invalid type' => [new Country(), 123, $unexpectedTypeMessage];
     }
 
     public static function provideRuleFailureConditionData(): \Generator
     {
         $exception = CountryException::class;
-        $message = '/The (.*) value is not a valid (.*) country code, (.*) given\./';
+        $message = '/The (.*) value is not a valid country, (.*) 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];
+        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'];
+        yield 'default' => [new Country(), 'pt'];
+        yield 'alpha2' => [new Country(code: 'alpha-2'), 'pt'];
+        yield 'alpha3' => [new Country(code: 'alpha-3'), 'prt'];
     }
 
     public static function provideRuleMessageOptionData(): \Generator

tests/LanguageTest.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Test;
+
+use ProgrammatorDev\Validator\Exception\LanguageException;
+use ProgrammatorDev\Validator\Rule\Language;
+use ProgrammatorDev\Validator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleUnexpectedValueTrait;
+
+class LanguageTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        $unexpectedCodeMessage = '/Invalid code "(.*)"\. Accepted values are\: "(.*)"\./';
+        $unexpectedTypeMessage = '/Expected value of type "string", (.*) given\./';
+
+        yield 'invalid code' => [new Language('invalid'), 'pt', $unexpectedCodeMessage];
+        yield 'invalid type' => [new Language(), 123, $unexpectedTypeMessage];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $exception = LanguageException::class;
+        $message = '/The (.*) value is not a valid language, (.*) given\./';
+
+        yield 'default' => [new Language(), 'prt', $exception, $message];
+        yield 'alpha2' => [new Language(code: 'alpha-2'), 'por', $exception, $message];
+        yield 'alpha3' => [new Language(code: 'alpha-3'), 'pt', $exception, $message];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'default' => [new Language(), 'pt'];
+        yield 'alpha2' => [new Language(code: 'alpha-2'), 'pt'];
+        yield 'alpha3' => [new Language(code: 'alpha-3'), 'por'];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new Language(
+                message: 'The {{ name }} value {{ value }} is not a valid {{ code }} language code.'
+            ),
+            'invalid',
+            'The test value "invalid" is not a valid "alpha-2" language code.'
+        ];
+    }
+}

tests/TimezoneTest.php

@@ -19,15 +19,15 @@ class TimezoneTest extends AbstractTest
     public static function provideRuleUnexpectedValueData(): \Generator
     {
         $unexpectedMissingCountryCodeMessage = '/A country code is required when timezone group is "\\\DateTimeZone::PER_COUNTRY"\./';
-        $unexpectedCountryCodeMessage = '/The (.*) value is not a valid (.*) country code, (.*) given\./';
+        $unexpectedCountryCodeMessage = '/The (.*) value is not a valid country, (.*) given\./';
 
         yield 'missing country code' => [
             new Timezone(\DateTimeZone::PER_COUNTRY),
             'Europe/Lisbon',
             $unexpectedMissingCountryCodeMessage
         ];
         yield 'invalid country code' => [
-            new Timezone(\DateTimeZone::PER_COUNTRY, 'PRT'),
+            new Timezone(\DateTimeZone::PER_COUNTRY, 'prt'),
             'Europe/Lisbon',
             $unexpectedCountryCodeMessage
         ];