feat: added Optional rule

Author: andrepimpao

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
+        ];
+    }
+}