Merge pull request #185 from cycle/feature/where-not

feat: Add support for the `NOT` operator in SQL queries. Add new methods `whereNot`, `andWhereNot`, and `orWhereNot`
to the query builder by @msmakouz (#185)

src/Driver/Compiler.php

@@ -422,6 +422,12 @@ protected function where(QueryParameters $params, Quoter $q, array $tokens): str
 
             // first condition in group/query, no any AND, OR required
             if ($activeGroup) {
+                // first condition can have a `NOT` keyword (WHERE NOT ...)
+                if (\str_contains(\strtoupper($boolean), 'NOT')) {
+                    $statement .= 'NOT';
+                    $statement .= ' ';
+                }
+
                 // next conditions require AND or OR
                 $activeGroup = false;
             } else {

src/Driver/CompilerInterface.php

@@ -27,6 +27,8 @@ interface CompilerInterface
 
     public const TOKEN_AND = '@AND';
     public const TOKEN_OR = '@OR';
+    public const TOKEN_AND_NOT = '@AND NOT';
+    public const TOKEN_OR_NOT = '@OR NOT';
 
     /**
      * @param string $identifier

src/Query/Traits/TokenTrait.php

@@ -52,12 +52,7 @@ protected function registerToken(string $boolean, array $params, array &$tokens,
                 }
 
                 if (\count($complex) === 1) {
-                    $this->flattenWhere(
-                        $boolean === 'AND' ? CompilerInterface::TOKEN_AND : CompilerInterface::TOKEN_OR,
-                        $complex,
-                        $tokens,
-                        $wrapper
-                    );
+                    $this->flattenWhere($this->booleanToToken($boolean), $complex, $tokens, $wrapper);
                     return;
                 }
 
@@ -161,7 +156,7 @@ protected function registerToken(string $boolean, array $params, array &$tokens,
      */
     private function flattenWhere(string $grouper, array $where, array &$tokens, callable $wrapper): void
     {
-        $boolean = ($grouper === CompilerInterface::TOKEN_AND ? 'AND' : 'OR');
+        $boolean = $this->tokenToBoolean($grouper);
 
         foreach ($where as $key => $value) {
             // Support for closures
@@ -175,7 +170,12 @@ private function flattenWhere(string $grouper, array $where, array &$tokens, cal
             $token = strtoupper($key);
 
             // Grouping identifier (@OR, @AND), MongoDB like style
-            if ($token === CompilerInterface::TOKEN_AND || $token === CompilerInterface::TOKEN_OR) {
+            if (
+                $token === CompilerInterface::TOKEN_AND ||
+                $token === CompilerInterface::TOKEN_OR ||
+                $token === CompilerInterface::TOKEN_AND_NOT ||
+                $token === CompilerInterface::TOKEN_OR_NOT
+            ) {
                 $tokens[] = [$boolean, '('];
 
                 foreach ($value as $nested) {
@@ -184,7 +184,7 @@ private function flattenWhere(string $grouper, array $where, array &$tokens, cal
                         continue;
                     }
 
-                    $tokens[] = [$token === CompilerInterface::TOKEN_AND ? 'AND' : 'OR', '('];
+                    $tokens[] = [$this->tokenToBoolean($token), '('];
                     $this->flattenWhere(CompilerInterface::TOKEN_AND, $nested, $tokens, $wrapper);
                     $tokens[] = ['', ')'];
                 }
@@ -267,4 +267,24 @@ private function pushCondition(string $innerJoiner, string $key, array $where, &
 
         return $tokens;
     }
+
+    private function tokenToBoolean(string $token): string
+    {
+        return match ($token) {
+            CompilerInterface::TOKEN_AND => 'AND',
+            CompilerInterface::TOKEN_AND_NOT => 'AND NOT',
+            CompilerInterface::TOKEN_OR_NOT => 'OR NOT',
+            default => 'OR',
+        };
+    }
+
+    private function booleanToToken(string $boolean): string
+    {
+        return match ($boolean) {
+            'AND' => CompilerInterface::TOKEN_AND,
+            'AND NOT' => CompilerInterface::TOKEN_AND_NOT,
+            'OR NOT' => CompilerInterface::TOKEN_OR_NOT,
+            default => 'OR',
+        };
+    }
 }

src/Query/Traits/WhereTrait.php

@@ -83,6 +83,69 @@ public function orWhere(mixed ...$args): self
         return $this;
     }
 
+    /**
+     * Simple WHERE NOT condition with various set of arguments.
+     *
+     * @param mixed ...$args [(column, value), (column, operator, value)]
+     *
+     * @throws BuilderException
+     *
+     * @return $this|self
+     */
+    public function whereNot(mixed ...$args): self
+    {
+        $this->registerToken(
+            'AND NOT',
+            $args,
+            $this->whereTokens,
+            $this->whereWrapper()
+        );
+
+        return $this;
+    }
+
+    /**
+     * Simple AND WHERE NOT condition with various set of arguments.
+     *
+     * @param mixed ...$args [(column, value), (column, operator, value)]
+     *
+     * @throws BuilderException
+     *
+     * @return $this|self
+     */
+    public function andWhereNot(mixed ...$args): self
+    {
+        $this->registerToken(
+            'AND NOT',
+            $args,
+            $this->whereTokens,
+            $this->whereWrapper()
+        );
+
+        return $this;
+    }
+
+    /**
+     * Simple OR WHERE NOT condition with various set of arguments.
+     *
+     * @param mixed ...$args [(column, value), (column, operator, value)]
+     *
+     * @throws BuilderException
+     *
+     * @return $this|self
+     */
+    public function orWhereNot(mixed ...$args): self
+    {
+        $this->registerToken(
+            'OR NOT',
+            $args,
+            $this->whereTokens,
+            $this->whereWrapper()
+        );
+
+        return $this;
+    }
+
     /**
      * Convert various amount of where function arguments into valid where token.
      *