Query hints

src/Comments.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace ipl\Sql;
+
+trait Comments
+{
+    /**
+     * The comments used
+     *
+     * @var array
+     */
+    protected $comments = [];
+
+    /**
+     * The hints used
+     *
+     * @var array
+     */
+    protected $hints = [];
+
+    public function addComment($comment)
+    {
+        $this->comments[] = $comment;
+
+        return $this;
+    }
+
+    public function getComments()
+    {
+        return $this->comments;
+    }
+
+    public function addHint($hint)
+    {
+        $this->hints[] = $hint;
+
+        return $this;
+    }
+
+    public function getHints()
+    {
+        return $this->hints;
+    }
+}

src/CommentsInterface.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace ipl\Sql;
+
+interface CommentsInterface
+{
+    /**
+     * Add simple text comment
+     *
+     * @param string $comment
+     *
+     * @return $this
+     */
+    public function addComment($comment);
+
+    /**
+     * Get all text comments
+     *
+     * @return array
+     */
+    public function getComments();
+
+    /**
+     * Add an optimizer hint
+     *
+     * @param string $hint
+     *
+     * @return $this
+     */
+    public function addHint($hint);
+
+    /**
+     * Get all hints
+     *
+     * @return array
+     */
+    public function getHints();
+}

src/QueryBuilder.php

@@ -107,7 +107,12 @@ public function assembleSelect(Select $select, array &$values = [])
     {
         $sql = array_filter([
             $this->buildWith($select->getWith(), $values),
-            $this->buildSelect($select->getColumns(), $select->getDistinct(), $values),
+            $this->buildSelect(
+                $this->buildComments($select->getComments(), $select->getHints()),
+                $select->getColumns(),
+                $select->getDistinct(),
+                $values
+            ),
             $this->buildFrom($select->getFrom(), $values),
             $this->buildJoin($select->getJoin(), $values),
             $this->buildWhere($select->getWhere(), $values),
@@ -199,6 +204,25 @@ public function buildWith(array $with, array &$values)
         return ($hasRecursive ? 'WITH RECURSIVE ' : 'WITH ') . implode(', ', $ctes);
     }
 
+    public function buildComments(array $comments, array $hints)
+    {
+        $result = '';
+
+        if (! empty($comments)) {
+            $result = '/* ' . join(', ', $comments) . ' */';
+        }
+
+        if (! empty($hints)) {
+            if ($result) {
+                $result .= ' ';
+            }
+
+            $result .= '/*+ ' . join(' ', $hints) . ' */';
+        }
+
+        return $result;
+    }
+
     /**
      * Build the DELETE FROM part of a query
      *
@@ -418,14 +442,18 @@ public function buildInsertColumnsAndValues(array $columns, array $insertValues,
      *
      * @return  string  The SELECT part of the query
      */
-    public function buildSelect(array $columns, $distinct, array &$values)
+    public function buildSelect($comments, array $columns, $distinct, array &$values)
     {
         if (empty($columns)) {
             return '';
         }
 
         $select = 'SELECT';
 
+        if ($comments) {
+            $select .= " $comments";
+        }
+
         if ($distinct) {
             $select .= ' DISTINCT';
         }

src/Select.php

@@ -5,10 +5,11 @@
 /**
  * SQL SELECT query
  */
-class Select implements CommonTableExpressionInterface, LimitOffsetInterface, OrderByInterface, WhereInterface
+class Select implements CommonTableExpressionInterface, LimitOffsetInterface, OrderByInterface, WhereInterface, CommentsInterface
 {
     use CommonTableExpression;
     use LimitOffset;
+    use Comments;
     use OrderBy;
     use Where;