Use FilterOptions::RETURN_ON_NULL in Filterer::execute()

Author: chadicus

src/Filterer.php

@@ -145,6 +145,7 @@ public function execute(array $input) : FilterResponse
             self::assertFiltersIsAnArray($filters, $field);
             $customError = self::validateCustomError($filters, $field);
             $throwOnError = self::validateThrowOnError($filters, $field);
+            $returnOnNull = self::validateReturnOnNull($filters, $field);
             unset($filters[FilterOptions::IS_REQUIRED]);//doesn't matter if required since we have this one
             unset($filters[FilterOptions::DEFAULT_VALUE]);//doesn't matter if there is a default since we have a value
             $conflicts = self::extractConflicts($filters, $field, $conflicts);
@@ -167,6 +168,9 @@ public function execute(array $input) : FilterResponse
                 try {
                     $this->addUsedInputToFilter($uses, $filteredInput, $field, $filter);
                     $input = call_user_func_array($function, $filter);
+                    if ($input === null && $returnOnNull) {
+                        break;
+                    }
                 } catch (Exception $exception) {
                     if ($throwOnError) {
                         throw $exception;
@@ -630,6 +634,24 @@ private static function validateThrowOnError(array &$filters, string $field) : b
         return $throwOnError;
     }
 
+    private static function validateReturnOnNull(array &$filters, string $field) : bool
+    {
+        if (!array_key_exists(FilterOptions::RETURN_ON_NULL, $filters)) {
+            return false;
+        }
+
+        $returnOnNull = $filters[FilterOptions::RETURN_ON_NULL];
+        if ($returnOnNull !== true && $returnOnNull !== false) {
+            throw new InvalidArgumentException(
+                sprintf(self::INVALID_BOOLEAN_FILTER_OPTION, FilterOptions::RETURN_ON_NULL, $field)
+            );
+        }
+
+        unset($filters[FilterOptions::RETURN_ON_NULL]);
+
+        return $returnOnNull;
+    }
+
     private static function validateCustomError(array &$filters, string $field)
     {
         $customError = null;

tests/FiltererTest.php

@@ -378,6 +378,12 @@ function (int $input, int $fieldOneValue) : int {
                     [],
                 ],
             ],
+            'returnOnNull filter option' => [
+                'spec' => ['field' => [FilterOptions::RETURN_ON_NULL => true, ['string', true], ['string']]],
+                'input' => ['field' => null],
+                'options' => [],
+                'result' => [true, ['field' => null], null, []],
+            ],
         ];
     }
 
@@ -424,6 +430,26 @@ public function executeValidatesThrowsOnError()
         $filterer->execute(['id' => 1]);
     }
 
+    /**
+     * @test
+     * @covers ::execute
+     */
+    public function executeValidatesReturnOnNull()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            sprintf(Filterer::INVALID_BOOLEAN_FILTER_OPTION, FilterOptions::RETURN_ON_NULL, 'id')
+        );
+        $specification = [
+            'id' => [
+                FilterOptions::RETURN_ON_NULL => 'abc',
+                ['uint'],
+            ],
+        ];
+        $filterer = new Filterer($specification);
+        $filterer->execute(['id' => 1]);
+    }
+
     /**
      * @test
      * @covers ::filter