Merge pull request #61 from programmatordev/YAPV-66-create-optional-rule

Create Optional rule

Author: andrepimpao

docs/03-rules.md

@@ -6,6 +6,7 @@
 - [Date Rules](#date-rules)
 - [Choice Rules](#choice-rules)
 - [Iterable Rules](#iterable-rules)
+- [Other Rules](#other-rules)
 
 ## Basic Rules
 
@@ -43,4 +44,8 @@
 
 - [Collection](03-rules_collection.md)
 - [EachValue](03-rules_each-value.md)
-- [EachKey](03-rules_each-key.md)
+- [EachKey](03-rules_each-key.md)
+
+## Other Rules
+
+- [Optional](03-rules_optional.md)

docs/03-rules_collection.md

@@ -32,7 +32,9 @@ Validator::collection(fields: [
     'age' => 25
 ]); // false ("name" is blank)
 
-// by default, unknown keys are not allowed
+///////////////////////////////
+
+// by default, extra fields are not allowed
 Validator::collection(fields: [
     'name' => Validator::notBlank(),
     'age' => Validator::type('int')->greaterThanOrEqual(18)
@@ -54,6 +56,26 @@ Validator::collection(
     'age' => 25,
     'email' => 'mail@example.com'
 ]); // true
+
+///////////////////////////////
+
+// by default, missing fields are not allowed
+Validator::collection(fields: [
+    'name' => Validator::notBlank(),
+    'age' => Validator::type('int')->greaterThanOrEqual(18)
+])->validate([
+    'age' => 25
+]); // false ("name" is missing)
+
+// but it is possible to use the Optional validation for optiona fields
+Validator::collection(fields: [
+    'name' => Validator::optional(
+        Validator::notBlank()
+    ),
+    'age' => Validator::type('int')->greaterThanOrEqual(18)
+])->validate([
+    'age' => 25
+]); // true ("name" is optional)
 ```
 
 > [!NOTE]

docs/03-rules_optional.md

@@ -0,0 +1,37 @@
+# Optional
+
+Validates only if value is *not* `null`.
+
+```php
+Optional(
+    Validator $validator,
+);
+```
+
+## Basic Usage
+
+```php
+Validator::optional(
+    Validator::type('int')->greaterThanEqualTo(18)
+)->validate(null); // true
+
+Validator::optional(
+    Validator::type('int')->greaterThanEqualTo(18)
+)->validate(20); // true
+
+Validator::optional(
+    Validator::type('int')->greaterThanEqualTo(18)
+)->validate(16); // false
+```
+
+## Options
+
+### `validator`
+
+type: `Validator` `required`
+
+Validator that will validate the input value only when it is *not* `null`.
+
+## Changelog
+
+- `1.0.0` Created

src/ChainedValidatorInterface.php

@@ -97,6 +97,10 @@ public function notBlank(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public function optional(
+        Validator $validator
+    ): ChainedValidatorInterface&Validator;
+
     public function passwordStrength(
         string $minStrength = 'medium',
         ?string $message = null

src/Rule/Collection.php

@@ -45,7 +45,10 @@ public function assert(mixed $value, ?string $name = null): void
         }
 
         foreach ($this->fields as $field => $validator) {
-            if (!isset($value[$field])) {
+            // find if validation is optional
+            $isOptional = $validator->getRules()[0] instanceof Optional;
+
+            if (!isset($value[$field]) && !$isOptional) {
                 throw new CollectionException(
                     message: $this->missingFieldsMessage,
                     parameters: [
@@ -55,6 +58,11 @@ public function assert(mixed $value, ?string $name = null): void
                 );
             }
 
+            // if value is not set but field is optional
+            if (!isset($value[$field]) && $isOptional) {
+                $value[$field] = null;
+            }
+
             try {
                 $validator->assert($value[$field], \sprintf('"%s"', $field));
             }

src/Rule/Optional.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Rule;
+
+use ProgrammatorDev\Validator\Validator;
+
+class Optional extends AbstractRule implements RuleInterface
+{
+    public function __construct(
+        private readonly Validator $validator
+    ) {}
+
+    public function assert(mixed $value, ?string $name = null): void
+    {
+        // validate only if value is not null
+        if ($value === null) {
+            return;
+        }
+
+        $this->validator->assert($value, $name);
+    }
+}

src/StaticValidatorInterface.php

@@ -96,6 +96,10 @@ public static function notBlank(
         ?string $message = null
     ): ChainedValidatorInterface&Validator;
 
+    public static function optional(
+        Validator $validator
+    ): ChainedValidatorInterface&Validator;
+
     public static function passwordStrength(
         string $minStrength = 'medium',
         ?string $message = null

tests/CollectionTest.php

@@ -37,14 +37,15 @@ public static function provideRuleUnexpectedValueData(): \Generator
     public static function provideRuleFailureConditionData(): \Generator
     {
         $exception = CollectionException::class;
+        $notBlankMessage = '/The "(.*)" value should not be blank, "" given\./';
         $extraFieldsMessage = '/The (.*) field is not allowed\./';
         $missingFieldsMessage = '/The (.*) field is missing\./';
 
         yield 'invalid field' => [
             new Collection(fields: ['field' => Validator::notBlank()]),
             ['field' => ''],
             $exception,
-            '/The "(.*)" value should not be blank, "" given\./'
+            $notBlankMessage
         ];
         yield 'extra fields' => [
             new Collection(fields: ['field' => Validator::notBlank()]),
@@ -53,16 +54,25 @@ public static function provideRuleFailureConditionData(): \Generator
             $extraFieldsMessage
         ];
         yield 'missing fields' => [
-            new Collection(
-                fields: [
-                    'field1' => Validator::notBlank(),
-                    'field2' => Validator::notBlank()
-                ]
-            ),
+            new Collection(fields: [
+                'field1' => Validator::notBlank(),
+                'field2' => Validator::notBlank()
+            ]),
             ['field1' => 'value1'],
             $exception,
             $missingFieldsMessage
         ];
+        yield 'optional' => [
+            new Collection(fields: [
+                'field' => Validator::notBlank(),
+                'optional' => Validator::optional(
+                    Validator::notBlank()
+                )
+            ]),
+            ['field' => 'value', 'optional' => ''],
+            $exception,
+            $notBlankMessage
+        ];
     }
 
     public static function provideRuleSuccessConditionData(): \Generator
@@ -82,6 +92,24 @@ public static function provideRuleSuccessConditionData(): \Generator
             ),
             ['field' => 'value', 'extrafield' => 'extravalue']
         ];
+        yield 'optional' => [
+            new Collection(fields: [
+                'field' => Validator::notBlank(),
+                'optional' => Validator::optional(
+                    Validator::notBlank()
+                )
+            ]),
+            ['field' => 'value']
+        ];
+        yield 'optional null' => [
+            new Collection(fields: [
+                'field' => Validator::notBlank(),
+                'optional' => Validator::optional(
+                    Validator::notBlank()
+                )
+            ]),
+            ['field' => 'value', 'optional' => null]
+        ];
     }
 
     public static function provideRuleMessageOptionData(): \Generator

tests/OptionalTest.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace ProgrammatorDev\Validator\Test;
+
+use ProgrammatorDev\Validator\Exception\NotBlankException;
+use ProgrammatorDev\Validator\Rule\NotBlank;
+use ProgrammatorDev\Validator\Rule\Optional;
+use ProgrammatorDev\Validator\Test\Util\TestRuleFailureConditionTrait;
+use ProgrammatorDev\Validator\Test\Util\TestRuleSuccessConditionTrait;
+use ProgrammatorDev\Validator\Validator;
+
+class OptionalTest extends AbstractTest
+{
+    use TestRuleFailureConditionTrait;
+    use TestRuleSuccessConditionTrait;
+
+    public static function provideRuleFailureConditionData(): \Generator
+    {
+        yield 'default' => [
+            new Optional(
+                new Validator(new NotBlank())
+            ),
+            '',
+            NotBlankException::class,
+            '/The (.*) value should not be blank, (.*) given\./'
+        ];
+    }
+
+    public static function provideRuleSuccessConditionData(): \Generator
+    {
+        yield 'default' => [
+            new Optional(
+                new Validator(new NotBlank())
+            ),
+            null
+        ];
+    }
+}