Update filter value requirements for falsy values (#24)

Co-authored-by: Chris Penny <chris.penny@gmail.com>

Author: alex-dna

src/Query/Filter/Criteria.php

@@ -100,8 +100,9 @@ public function filter(Clause|string $targetOrClause, mixed $value = null, ?stri
             return $this;
         }
 
-        if (!$value) {
-            throw new Exception('mixed $value and string $comparison expected for filter()');
+        // Only NULL_COMPARISONS support a $value of null. All other falsy values are allowed
+        if ($value === null && !in_array($comparison, Criterion::NULL_COMPARISONS, true)) {
+            throw new Exception('mixed $value of null is not supported outside of NULL_COMPARISON filters');
         }
 
         if (!$comparison) {

src/Query/Filter/Criterion.php

@@ -42,6 +42,11 @@ class Criterion implements Clause
         self::RANGE,
     ];
 
+    public const NULL_COMPARISONS = [
+        self::IS_NULL,
+        self::IS_NOT_NULL,
+    ];
+
     private ?CriterionAdaptor $adaptor = null;
 
     private static array $dependencies = [

tests/Query/QueryTest.php

@@ -204,25 +204,39 @@ public function testFilterWithClause(): void
         $query = Query::create();
         $criterionOne = Criterion::create('field1', 'value1', Criterion::EQUAL);
         $criterionTwo = Criterion::create('field2', 'value2', Criterion::EQUAL);
+        $criterionThree = Criterion::create('field3', '', Criterion::NOT_EQUAL);
+        $criterionFour = Criterion::create('field4', 0, Criterion::NOT_EQUAL);
 
         $query->filter($criterionOne);
         $query->filter($criterionTwo);
+        $query->filter($criterionThree);
+        $query->filter($criterionFour);
 
         $clauses = $query->getFilter()->getClauses();
 
-        $this->assertCount(2, $clauses);
+        $this->assertCount(4, $clauses);
 
         /** @var Criterion $criterionOne */
         $criterionOne = array_shift($clauses);
         /** @var Criterion $criterionTwo */
         $criterionTwo = array_shift($clauses);
+        /** @var Criterion $criterionThree */
+        $criterionThree = array_shift($clauses);
+        /** @var Criterion $criterionFour */
+        $criterionFour = array_shift($clauses);
 
         $this->assertEquals('field1', $criterionOne->getTarget());
         $this->assertEquals('value1', $criterionOne->getValue());
         $this->assertEquals(Criterion::EQUAL, $criterionOne->getComparison());
         $this->assertEquals('field2', $criterionTwo->getTarget());
         $this->assertEquals('value2', $criterionTwo->getValue());
         $this->assertEquals(Criterion::EQUAL, $criterionTwo->getComparison());
+        $this->assertEquals('field3', $criterionThree->getTarget());
+        $this->assertEquals('', $criterionThree->getValue());
+        $this->assertEquals(Criterion::NOT_EQUAL, $criterionThree->getComparison());
+        $this->assertEquals('field4', $criterionFour->getTarget());
+        $this->assertEquals(0, $criterionFour->getValue());
+        $this->assertEquals(Criterion::NOT_EQUAL, $criterionFour->getComparison());
     }
 
     public function testFilterWithTarget(): void
@@ -256,7 +270,8 @@ public function testFilterAny(): void
         $query->filterAny([
             $criterion,
             ['field2', 'value2', Criterion::EQUAL],
-            ['field3', 'value3', Criterion::EQUAL],
+            ['field3', '', Criterion::NOT_EQUAL],
+            ['field4', 0, Criterion::NOT_EQUAL],
         ]);
 
         $clauses = $query->getFilter()->getClauses();
@@ -278,6 +293,8 @@ public function testFilterAny(): void
         $criterionTwo = array_shift($clauses);
         /** @var Criterion $criterionThree */
         $criterionThree = array_shift($clauses);
+        /** @var Criterion $criterionFour */
+        $criterionFour = array_shift($clauses);
 
         $this->assertEquals('field1', $criterionOne->getTarget());
         $this->assertEquals('value1', $criterionOne->getValue());
@@ -286,13 +303,16 @@ public function testFilterAny(): void
         $this->assertEquals('value2', $criterionTwo->getValue());
         $this->assertEquals(Criterion::EQUAL, $criterionTwo->getComparison());
         $this->assertEquals('field3', $criterionThree->getTarget());
-        $this->assertEquals('value3', $criterionThree->getValue());
-        $this->assertEquals(Criterion::EQUAL, $criterionThree->getComparison());
+        $this->assertEquals('', $criterionThree->getValue());
+        $this->assertEquals(Criterion::NOT_EQUAL, $criterionThree->getComparison());
+        $this->assertEquals('field4', $criterionFour->getTarget());
+        $this->assertEquals(0, $criterionFour->getValue());
+        $this->assertEquals(Criterion::NOT_EQUAL, $criterionFour->getComparison());
     }
 
     public function testFilterNoValue(): void
     {
-        $this->expectExceptionMessage('mixed $value and string $comparison expected for filter()');
+        $this->expectExceptionMessage('mixed $value of null is not supported outside of NULL_COMPARISON filters');
 
         $query = Query::create();
         // Should throw our exception