Merge pull request #38 from programmatordev/YAPV-50-create-eachkey-rule

Create EachKey rule

Author: andrepimpao

docs/03-rules.md

@@ -30,4 +30,5 @@
 
 ## Iterable Rules
 
-- [EachValue](03x-rules-eachvalue.md)
+- [EachValue](03x-rules-each-value.md)
+- [EachKey](03x-rules-each-key.md)

docs/03x-rules-each-key.md

@@ -0,0 +1,49 @@
+## EachKey
+
+Validates every key of an `array` or object implementing `\Traversable` with a given set of rules.
+
+```php
+EachKey(
+    Validator $validator,
+    string $message = 'Invalid key: {{ message }}'
+);
+```
+
+## Basic Usage
+
+```php
+Validator::eachKey(Validator::notBlank()->type('string'))->validate(['red' => '#f00', 'green' => '#0f0']); // true
+Validator::eachKey(Validator::notBlank()->type('string'))->validate(['red' => '#f00', 1 => '#0f0']); // false
+```
+
+> **Note**
+> An `UnexpectedValueException` will be thrown when the input value is not an `array` or an object implementing `\Traversable`.
+
+## Options
+
+### `validator`
+
+type: `Validator` `required`
+
+Validator that will validate each key of an `array` or object implementing `\Traversable`.
+
+### `message`
+
+type: `string` default: `Invalid key: {{ message }}`
+
+Message that will be shown if at least one input value key is invalid according to the given `validator`.
+
+```php
+Validator::eachKey(Validator::notBlank())->assert(['red' => '#f00', 1 => '#0f0'], 'Test'); 
+// Throws: Invalid key: The "Test" key should be of type "string", "1" given.
+```
+
+The following parameters are available:
+
+| Parameter       | Description                                      |
+|-----------------|--------------------------------------------------|
+| `{{ value }}`   | The current invalid value                        |
+| `{{ name }}`    | Name of the invalid value                        |
+| `{{ key }}`     | The key of the invalid iterable element          |
+| `{{ element }}` | The value of the invalid iterable element        |
+| `{{ message }}` | The rule message of the invalid iterable element |

docs/03x-rules-eachvalue.md renamed to docs/03x-rules-each-value.md

@@ -45,4 +45,5 @@ The following parameters are available:
 | `{{ value }}`   | The current invalid value                        |
 | `{{ name }}`    | Name of the invalid value                        |
 | `{{ key }}`     | The key of the invalid iterable element          |
+| `{{ element }}` | The value of the invalid iterable element        |
 | `{{ message }}` | The rule message of the invalid iterable element |

src/ChainedValidatorInterface.php

@@ -23,6 +23,11 @@ public function country(
         string $message = 'The "{{ name }}" value is not a valid "{{ code }}" country code, "{{ value }}" given.'
     ): ChainedValidatorInterface&Validator;
 
+    public function eachKey(
+        Validator $validator,
+        string $message = 'Invalid key: {{ message }}'
+    ): ChainedValidatorInterface&Validator;
+
     public function eachValue(
         Validator $validator,
         string $message = 'At key "{{ key }}": {{ message }}'

src/Exception/EachKeyException.php

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

src/Rule/EachKey.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Rule;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\EachKeyException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\UnexpectedValueException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+class EachKey extends AbstractRule implements RuleInterface
+{
+    public function __construct(
+        private readonly Validator $validator,
+        private readonly string $message = 'Invalid key: {{ message }}'
+    ) {}
+
+    public function assert(mixed $value, string $name): void
+    {
+        if (!\is_iterable($value)) {
+            throw new UnexpectedValueException(
+                \sprintf('Expected value of type "array|\Traversable", "%s" given.', get_debug_type($value))
+            );
+        }
+
+        try {
+            foreach ($value as $key => $element) {
+                $this->validator->assert($key, $name);
+            }
+        }
+        catch (ValidationException $exception) {
+            throw new EachKeyException(
+                message: $this->message,
+                parameters: [
+                    'value' => $value,
+                    'name' => $name,
+                    'key' => $key,
+                    'element' => $element,
+                    // Replaces string "value" with string "key" to get a more intuitive error message
+                    'message' => \preg_replace(
+                        \sprintf('/"(%s)" value/', $name),
+                        '"$1" key',
+                        $exception->getMessage()
+                    )
+                ]
+            );
+        }
+    }
+}

src/Rule/EachValue.php

@@ -23,8 +23,8 @@ public function assert(mixed $value, string $name): void
         }
 
         try {
-            foreach ($value as $key => $input) {
-                $this->validator->assert($input, $name);
+            foreach ($value as $key => $element) {
+                $this->validator->assert($element, $name);
             }
         }
         catch (ValidationException $exception) {
@@ -34,6 +34,7 @@ public function assert(mixed $value, string $name): void
                     'value' => $value,
                     'name' => $name,
                     'key' => $key,
+                    'element' => $element,
                     'message' => $exception->getMessage()
                 ]
             );

src/StaticValidatorInterface.php

@@ -22,6 +22,11 @@ public static function country(
         string $message = 'The "{{ name }}" value is not a valid "{{ code }}" country code, "{{ value }}" given.'
     ): ChainedValidatorInterface&Validator;
 
+    public static function eachKey(
+        Validator $validator,
+        string $message = 'Invalid key: {{ message }}'
+    ): ChainedValidatorInterface&Validator;
+
     public static function eachValue(
         Validator $validator,
         string $message = 'At key "{{ key }}": {{ message }}'

tests/EachKeyTest.php

@@ -0,0 +1,79 @@
+<?php
+
+namespace ProgrammatorDev\YetAnotherPhpValidator\Test;
+
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\EachKeyException;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\EachKey;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\GreaterThan;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\NotBlank;
+use ProgrammatorDev\YetAnotherPhpValidator\Rule\Type;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleMessageOptionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Test\Util\TestRuleUnexpectedValueTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+class EachKeyTest extends AbstractTest
+{
+    use TestRuleUnexpectedValueTrait;
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+    use TestRuleMessageOptionTrait;
+
+    public static function provideRuleUnexpectedValueData(): \Generator
+    {
+        yield 'invalid value type' => [
+            new EachKey(new Validator(new Type('string'))),
+            'invalid',
+            '/Expected value of type "(.*)", "(.*)" given./'
+        ];
+        yield 'unexpected value propagation' => [
+            new EachKey(new Validator(new GreaterThan(10))),
+            ['key1' => 1],
+            '/Cannot compare a type "(.*)" with a type "(.*)"./'
+        ];
+    }
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        $exception = EachKeyException::class;
+        $message = '/Invalid key: The "(.*)" key should be of type "(.*)", "(.*)" given./';
+
+        yield 'invalid array element' => [
+            new EachKey(new Validator(new Type('string'))),
+            ['key1' => 1, 'key2' => 2, 1 => 3],
+            $exception,
+            $message
+        ];
+        yield 'invalid traversable element' => [
+            new EachKey(new Validator(new Type('string'))),
+            new \ArrayIterator(['key1' => 1, 'key2' => 2, 1 => 3]),
+            $exception,
+            $message
+        ];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'array element' => [
+            new EachKey(new Validator(new Type('string'))),
+            ['key1' => 1, 'key2' => 2, 'key3' => 3]
+        ];
+        yield 'traversable element' => [
+            new EachKey(new Validator(new Type('string'))),
+            new \ArrayIterator(['key1' => 1, 'key2' => 2, 'key3' => 3])
+        ];
+    }
+
+    public static function provideRuleMessageOptionData(): \Generator
+    {
+        yield 'message' => [
+            new EachKey(
+                validator: new Validator(new Type('string')),
+                message: 'The "{{ name }}" key "{{ key }}" is invalid.'
+            ),
+            ['key1' => 1, 'key2' => 2, 1 => 3],
+            'The "test" key "1" is invalid.'
+        ];
+    }
+}