feat: add withComment method to add comments

src/Query/QueryBuilder.php

@@ -17,6 +17,7 @@
 use function array_key_exists;
 use function array_keys;
 use function array_unshift;
+use function array_map;
 use function count;
 use function func_get_arg;
 use function func_get_args;
@@ -82,6 +83,7 @@
         'orderBy'    => [],
         'values'     => [],
         'for_update' => null,
+        'comment'    => [],
     ];
 
     /**
@@ -411,21 +413,23 @@
             return $this->sql;
         }
 
+        $sql = $this->getComments();
+
         switch ($this->type) {
             case self::INSERT:
-                $sql = $this->getSQLForInsert();
+                $sql .= $this->getSQLForInsert();
                 break;
 
             case self::DELETE:
-                $sql = $this->getSQLForDelete();
+                $sql .= $this->getSQLForDelete();
                 break;
 
             case self::UPDATE:
-                $sql = $this->getSQLForUpdate();
+                $sql .= $this->getSQLForUpdate();
                 break;
 
             case self::SELECT:
-                $sql = $this->getSQLForSelect();
+                $sql .= $this->getSQLForSelect();
                 break;
         }
 
@@ -636,6 +640,7 @@
                 || $sqlPartName === 'groupBy'
                 || $sqlPartName === 'select'
                 || $sqlPartName === 'set'
+                || $sqlPartName === 'comment'
             ) {
                 foreach ($sqlPart as $part) {
                     $this->sqlParts[$sqlPartName][] = $part;
@@ -1756,4 +1761,18 @@
 
         return $this;
     }
+
+    public function withComment(string $comment): self
+    {
+        $this->add('comment', $comment, true);
+
+        return $this;
+    }
+
+    private function getComments(): string
+    {
+        return implode('', array_map(function ($comment) {
+            return sprintf('/* %s */ ', $comment);
+        }, $this->sqlParts['comment']));
+    }
 }

tests/Query/QueryBuilderTest.php

@@ -421,6 +421,29 @@ public function testSelectMultipleFrom(): void
         self::assertEquals('SELECT u.*, p.* FROM users u, phonenumbers p', (string) $qb);
     }
 
+    public function testSelectWithComment(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+
+        $qb->select('u.id')
+            ->from('users', 'u')
+            ->withComment('Test comment');
+
+        self::assertEquals('/* Test comment */ SELECT u.id FROM users u', (string) $qb);
+    }
+
+    public function testSelectWithCommentMultiple(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+
+        $qb->select('u.id')
+            ->from('users', 'u')
+            ->withComment('Test comment')
+            ->withComment('Second comment');
+
+        self::assertEquals('/* Test comment */ /* Second comment */ SELECT u.id FROM users u', (string) $qb);
+    }
+
     public function testUpdate(): void
     {
         $qb = new QueryBuilder($this->conn);
@@ -432,6 +455,18 @@ public function testUpdate(): void
         self::assertEquals('UPDATE users u SET u.foo = ?, u.bar = ?', (string) $qb);
     }
 
+    public function testUpdateWithComment(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+        $qb->update('users', 'u')
+           ->set('u.foo', '?')
+           ->set('u.bar', '?')
+           ->withComment('Test comment');
+
+        self::assertEquals(QueryBuilder::UPDATE, $qb->getType());
+        self::assertEquals('/* Test comment */ UPDATE users u SET u.foo = ?, u.bar = ?', (string) $qb);
+    }
+
     public function testUpdateWithoutAlias(): void
     {
         $qb = new QueryBuilder($this->conn);
@@ -470,6 +505,16 @@ public function testDelete(): void
         self::assertEquals('DELETE FROM users u', (string) $qb);
     }
 
+    public function testDeleteWithComment(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+        $qb->delete('users', 'u')
+           ->withComment('Test comment');
+
+        self::assertEquals(QueryBuilder::DELETE, $qb->getType());
+        self::assertEquals('/* Test comment */ DELETE FROM users u', (string) $qb);
+    }
+
     public function testDeleteWithoutAlias(): void
     {
         $qb = new QueryBuilder($this->conn);
@@ -512,6 +557,16 @@ public function testInsertValues(): void
         self::assertEquals('INSERT INTO users (foo, bar) VALUES(?, ?)', (string) $qb);
     }
 
+    public function testInsertWithComment(): void
+    {
+        $qb = new QueryBuilder($this->conn);
+        $qb->insert('users')
+            ->withComment('Test comment');
+
+        self::assertEquals(QueryBuilder::INSERT, $qb->getType());
+        self::assertEquals('/* Test comment */ INSERT INTO users () VALUES()', (string) $qb);
+    }
+
     public function testInsertReplaceValues(): void
     {
         $qb = new QueryBuilder($this->conn);