Merge pull request #348 from remi-san/not-expression

`NOT` CompositeExpression in order to filter-out values

docs/en/expression-builder.rst

@@ -42,6 +42,18 @@ orX
 
     $collection->matching(new Criteria($expression));
 
+not
+---
+
+.. code-block:: php
+    $expressionBuilder = Criteria::expr();
+
+    $expression = $expressionBuilder->not(
+        $expressionBuilder->eq('foo', 1)
+    );
+
+    $collection->matching(new Criteria($expression));
+
 eq
 ---
 

docs/en/expressions.rst

@@ -2,7 +2,7 @@ Expressions
 ===========
 
 The ``Doctrine\Common\Collections\Expr\Comparison`` class
-can be used to create expressions to be used with the
+can be used to create comparison expressions to be used with the
 ``Doctrine\Common\Collections\Criteria`` class. It has the
 following operator constants:
 
@@ -20,6 +20,19 @@ following operator constants:
 - ``Comparison::STARTS_WITH``
 - ``Comparison::ENDS_WITH``
 
+The ``Doctrine\Common\Collections\Expr\CompositeExpression`` class
+can be used to create composite expressions to be used with the
+``Doctrine\Common\Collections\Criteria`` class. It has the
+following operator constants:
+
+- ``CompositeExpression::TYPE_AND``
+- ``CompositeExpression::TYPE_OR``
+- ``CompositeExpression::TYPE_NOT``
+
+When using the ``TYPE_OR`` and ``TYPE_AND`` operators the
+``CompositeExpression`` accepts multiple expressions as parameter
+but only one expression can be provided when using the ``NOT`` operator.
+
 The ``Doctrine\Common\Collections\Criteria`` class has the following
 API to be used with expressions:
 

src/Expr/ClosureExpressionVisitor.php

@@ -181,6 +181,7 @@ public function walkCompositeExpression(CompositeExpression $expr)
         return match ($expr->getType()) {
             CompositeExpression::TYPE_AND => $this->andExpressions($expressionList),
             CompositeExpression::TYPE_OR => $this->orExpressions($expressionList),
+            CompositeExpression::TYPE_NOT => $this->notExpression($expressionList),
             default => throw new RuntimeException('Unknown composite ' . $expr->getType()),
         };
     }
@@ -212,4 +213,10 @@ private function orExpressions(array $expressions): Closure
             return false;
         };
     }
+
+    /** @param callable[] $expressions */
+    private function notExpression(array $expressions): Closure
+    {
+        return static fn ($object) => ! $expressions[0]($object);
+    }
 }

src/Expr/CompositeExpression.php

@@ -6,13 +6,16 @@
 
 use RuntimeException;
 
+use function count;
+
 /**
  * Expression of Expressions combined by AND or OR operation.
  */
 class CompositeExpression implements Expression
 {
     final public const TYPE_AND = 'AND';
     final public const TYPE_OR  = 'OR';
+    final public const TYPE_NOT = 'NOT';
 
     /** @var list<Expression> */
     private array $expressions = [];
@@ -35,6 +38,10 @@ public function __construct(private readonly string $type, array $expressions)
 
             $this->expressions[] = $expr;
         }
+
+        if ($type === self::TYPE_NOT && count($this->expressions) !== 1) {
+            throw new RuntimeException('Not expression only allows one expression as child.');
+        }
     }
 
     /**

src/ExpressionBuilder.php

@@ -30,6 +30,11 @@ public function orX(Expression ...$expressions)
         return new CompositeExpression(CompositeExpression::TYPE_OR, $expressions);
     }
 
+    public function not(Expression $expression): CompositeExpression
+    {
+        return new CompositeExpression(CompositeExpression::TYPE_NOT, [$expression]);
+    }
+
     /** @return Comparison */
     public function eq(string $field, mixed $value)
     {

tests/Common/Collections/ClosureExpressionVisitorTest.php

@@ -338,6 +338,18 @@ public function testWalkAndOrCompositeExpression(): void
         self::assertFalse($closure(new TestObject(0, 4)));
     }
 
+    public function testWalkNotCompositeExpression(): void
+    {
+        $closure = $this->visitor->walkCompositeExpression(
+            $this->builder->not(
+                $this->builder->eq('foo', 1),
+            ),
+        );
+
+        self::assertFalse($closure(new TestObject(1)));
+        self::assertTrue($closure(new TestObject(0)));
+    }
+
     public function testWalkUnknownCompositeExpressionThrowException(): void
     {
         self::expectException(RuntimeException::class);

tests/Common/Collections/Expr/CompositeExpressionTest.php

@@ -14,21 +14,23 @@
 /** @covers  \Doctrine\Common\Collections\Expr\CompositeExpression */
 class CompositeExpressionTest extends TestCase
 {
-    /** @return list<array{expression: mixed}> */
+    /** @return list<array{type:string, expressions: list<mixed>}> */
     public function invalidDataProvider(): array
     {
         return [
-            ['expression' => new Value('value')],
-            ['expression' => 'wrong-type'],
+            ['type' => CompositeExpression::TYPE_AND, 'expressions' => [new Value('value')]],
+            ['type' => CompositeExpression::TYPE_AND, 'expressions' => ['wrong-type']],
+            ['type' => CompositeExpression::TYPE_NOT, 'expressions' => [$this->createMock(Expression::class), $this->createMock(Expression::class)]],
         ];
     }
 
-    /** @dataProvider invalidDataProvider */
-    public function testExceptions(string|Value $expression): void
+    /**
+     * @param list<mixed> $expressions
+     *
+     * @dataProvider invalidDataProvider
+     */
+    public function testExceptions(string $type, array $expressions): void
     {
-        $type        = CompositeExpression::TYPE_AND;
-        $expressions = [$expression];
-
         $this->expectException(RuntimeException::class);
         new CompositeExpression($type, $expressions);
     }