Add advanced join clauses

Author: Daniel Opitz

docs/readme.md

@@ -250,12 +250,19 @@ CROSS JOIN `posts` ON `users`.`id` = `posts`.`user_id`;
 #### Advanced Join Clauses
 
 You may also specify more advanced join clauses. 
-To get started, pass a Closure as the second argument into 
-the join method. The Closure will receive a JoinClause object 
-which allows you to specify constraints on the join clause:
+To get started, pass a RawExp as the second argument into 
+the `joinRaw` and `leftJoinRaw` method.
 
+```php
+$users = $this->select()
+    ->from('users AS u')
+    ->joinRaw('posts AS p', new RawExp('p.user_id=u.id AND u.enabled=1 OR p.published IS NULL'))
+    ->execute()
+    ->fetchAll();
 ```
-Not supported.
+
+```sql
+SELECT `id` FROM `users` AS `u` INNER JOIN `posts` AS `p` ON (p.user_id=u.id AND u.enabled=1 OR p.published IS NULL);
 ```
 
 ### Unions

src/Database/SelectQuery.php

@@ -17,6 +17,7 @@ class SelectQuery extends SelectQueryBuilder implements QueryInterface
     public function distinct(): self
     {
         $this->distinct = 'DISTINCT';
+
         return $this;
     }
 
@@ -28,6 +29,7 @@ public function distinct(): self
     public function distinctRow(): self
     {
         $this->distinct = 'DISTINCTROW';
+
         return $this;
     }
 
@@ -39,6 +41,7 @@ public function distinctRow(): self
     public function straightJoin(): self
     {
         $this->straightJoin = 'STRAIGHT_JOIN';
+
         return $this;
     }
 
@@ -50,6 +53,7 @@ public function straightJoin(): self
     public function highPriority(): self
     {
         $this->highPriority = 'HIGH_PRIORITY';
+
         return $this;
     }
 
@@ -61,6 +65,7 @@ public function highPriority(): self
     public function smallResult(): self
     {
         $this->resultSize = 'SQL_SMALL_RESULT';
+
         return $this;
     }
 
@@ -72,6 +77,7 @@ public function smallResult(): self
     public function bigResult(): self
     {
         $this->resultSize = 'SQL_BIG_RESULT';
+
         return $this;
     }
 
@@ -83,6 +89,7 @@ public function bigResult(): self
     public function bufferResult(): self
     {
         $this->bufferResult = 'SQL_BUFFER_RESULT';
+
         return $this;
     }
 
@@ -94,6 +101,7 @@ public function bufferResult(): self
     public function calcFoundRows(): self
     {
         $this->calcFoundRows = 'SQL_CALC_FOUND_ROWS';
+
         return $this;
     }
 
@@ -106,6 +114,7 @@ public function calcFoundRows(): self
     public function columns(...$columns): self
     {
         $this->columns = $columns;
+
         return $this;
     }
 
@@ -118,6 +127,7 @@ public function columns(...$columns): self
     public function alias(string $alias): self
     {
         $this->alias = $alias;
+
         return $this;
     }
 
@@ -130,6 +140,7 @@ public function alias(string $alias): self
     public function from(string $table): self
     {
         $this->from = $table;
+
         return $this;
     }
 
@@ -143,6 +154,7 @@ public function from(string $table): self
     public function union(SelectQuery $query): self
     {
         $this->union[] = ['', $query->build(false)];
+
         return $this;
     }
 
@@ -156,6 +168,7 @@ public function union(SelectQuery $query): self
     public function unionAll(SelectQuery $query): self
     {
         $this->union[] = ['ALL', $query->build(false)];
+
         return $this;
     }
 
@@ -169,6 +182,7 @@ public function unionAll(SelectQuery $query): self
     public function unionDistinct(SelectQuery $query): self
     {
         $this->union[] = ['DISTINCT', $query->build(false)];
+
         return $this;
     }
 
@@ -184,6 +198,7 @@ public function unionDistinct(SelectQuery $query): self
     public function join(string $table, string $leftField, string $comparison, $rightField): self
     {
         $this->join[] = ['inner', $table, $leftField, $comparison, $rightField];
+
         return $this;
     }
 
@@ -199,6 +214,7 @@ public function join(string $table, string $leftField, string $comparison, $righ
     public function leftJoin(string $table, string $leftField, string $comparison, $rightField): self
     {
         $this->join[] = ['left', $table, $leftField, $comparison, $rightField];
+
         return $this;
     }
 
@@ -214,6 +230,49 @@ public function leftJoin(string $table, string $leftField, string $comparison, $
     public function crossJoin(string $table, string $leftField, string $comparison, $rightField): self
     {
         $this->join[] = ['cross', $table, $leftField, $comparison, $rightField];
+
+        return $this;
+    }
+
+    /**
+     * Join with complex conditions.
+     *
+     * @param string $table Table name
+     * @param RawExp $raw
+     * @return self
+     */
+    public function joinRaw(string $table, RawExp $raw): self
+    {
+        $this->join[] = ['inner', $table, $raw, null, null, null];
+
+        return $this;
+    }
+
+    /**
+     * Left join with complex conditions.
+     *
+     * @param string $table Table name
+     * @param RawExp $raw
+     * @return self
+     */
+    public function leftJoinRaw(string $table, RawExp $raw): self
+    {
+        $this->join[] = ['left', $table, $raw, null, null, null];
+
+        return $this;
+    }
+
+    /**
+     * Cross join with complex conditions.
+     *
+     * @param string $table Table name
+     * @param RawExp $raw
+     * @return self
+     */
+    public function crossJoinRaw(string $table, RawExp $raw): self
+    {
+        $this->join[] = ['cross', $table, $raw, null, null, null];
+
         return $this;
     }
 
@@ -228,6 +287,7 @@ public function crossJoin(string $table, string $leftField, string $comparison,
     public function where(...$conditions): self
     {
         $this->condition->where($conditions);
+
         return $this;
     }
 
@@ -242,6 +302,7 @@ public function where(...$conditions): self
     public function orWhere(...$conditions): self
     {
         $this->condition->orWhere($conditions);
+
         return $this;
     }
 
@@ -257,6 +318,7 @@ public function whereColumn(string $column, string $comparison, string $secondCo
     {
         $secondColumn = $this->quoter->quoteName($secondColumn);
         $this->condition->where([$column, $comparison, new RawExp($secondColumn)]);
+
         return $this;
     }
 
@@ -272,6 +334,7 @@ public function orWhereColumn(string $column, string $comparison, string $second
     {
         $secondColumn = $this->quoter->quoteName($secondColumn);
         $this->condition->orWhere([$column, $comparison, new RawExp($secondColumn)]);
+
         return $this;
     }
 
@@ -284,6 +347,7 @@ public function orWhereColumn(string $column, string $comparison, string $second
     public function orderBy(...$fields): self
     {
         $this->orderBy = $fields;
+
         return $this;
     }
 
@@ -296,6 +360,7 @@ public function orderBy(...$fields): self
     public function groupBy(...$fields): self
     {
         $this->groupBy = $fields;
+
         return $this;
     }
 
@@ -310,6 +375,7 @@ public function groupBy(...$fields): self
     public function having(...$conditions): self
     {
         $this->condition->having($conditions);
+
         return $this;
     }
 
@@ -324,6 +390,7 @@ public function having(...$conditions): self
     public function orHaving(...$conditions): self
     {
         $this->condition->orHaving($conditions);
+
         return $this;
     }
 
@@ -336,6 +403,7 @@ public function orHaving(...$conditions): self
     public function limit(float $rowCount): self
     {
         $this->limit = $rowCount;
+
         return $this;
     }
 
@@ -348,6 +416,7 @@ public function limit(float $rowCount): self
     public function offset(float $offset): self
     {
         $this->offset = $offset;
+
         return $this;
     }
 

src/Database/SelectQueryBuilder.php

@@ -208,9 +208,13 @@ protected function getJoinSql(array $sql): array
             list($type, $table, $leftField, $operator, $rightField) = $item;
             $joinType = strtoupper($type) . ' JOIN';
             $table = $this->quoter->quoteName($table);
-            $leftField = $this->quoter->quoteName($leftField);
-            $rightField = $this->quoter->quoteName($rightField);
-            $sql[] = sprintf('%s %s ON %s %s %s', $joinType, $table, $leftField, $operator, $rightField);
+            if($leftField instanceof RawExp) {
+                $sql[] = sprintf('%s %s ON (%s)', $joinType, $table, $leftField->getValue());
+            } else {
+                $leftField = $this->quoter->quoteName($leftField);
+                $rightField = $this->quoter->quoteName($rightField);
+                $sql[] = sprintf('%s %s ON %s %s %s', $joinType, $table, $leftField, $operator, $rightField);
+            }
         }
         return $sql;
     }

tests/SelectQueryTest.php

@@ -574,16 +574,73 @@ public function testJoin()
     {
         $select = $this->select()
             ->columns('id')
-            ->from('test')
-            ->join('users u', 'u.id', '=', 'test.user_id');
+            ->from('test AS t')
+            ->join('users AS u', 'u.id', '=', 'test.user_id');
         $this->assertInstanceOf(PDOStatement::class, $select->prepare());
-        $this->assertSame("SELECT `id` FROM `test` INNER JOIN `users` `u` ON `u`.`id` = `test`.`user_id`;", $select->build());
+        $this->assertSame("SELECT `id` FROM `test` AS `t` INNER JOIN `users` AS `u` ON `u`.`id` = `test`.`user_id`;", $select->build());
 
         $select->join('table2 AS t2', 't2.id', '=', 'test.user_id');
-        $expected = "SELECT `id` FROM `test` INNER JOIN `users` `u` ON `u`.`id` = `test`.`user_id` INNER JOIN `table2` AS `t2` ON `t2`.`id` = `test`.`user_id`;";
+        $expected = "SELECT `id` FROM `test` AS `t` INNER JOIN `users` AS `u` ON `u`.`id` = `test`.`user_id` INNER JOIN `table2` AS `t2` ON `t2`.`id` = `test`.`user_id`;";
         $this->assertSame($expected, $select->build());
     }
 
+    /**
+     * Test
+     *
+     * @covers ::joinRaw
+     * @covers ::getJoinSql
+     * @covers ::from
+     * @covers ::prepare
+     * @covers ::build
+     */
+    public function testJoinRaw()
+    {
+        $select = $this->select()
+            ->columns('id')
+            ->from('test')
+            ->joinRaw('users u', new RawExp('t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL'));
+        $this->assertInstanceOf(PDOStatement::class, $select->prepare());
+        $this->assertSame("SELECT `id` FROM `test` INNER JOIN `users` `u` ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL);", $select->build());
+    }
+
+    /**
+     * Test
+     *
+     * @covers ::leftJoinRaw
+     * @covers ::getJoinSql
+     * @covers ::from
+     * @covers ::prepare
+     * @covers ::build
+     */
+    public function testLeftJoinRaw()
+    {
+        $select = $this->select()
+            ->columns('id')
+            ->from('test')
+            ->leftJoinRaw('users u', new RawExp('t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL'));
+        $this->assertInstanceOf(PDOStatement::class, $select->prepare());
+        $this->assertSame("SELECT `id` FROM `test` LEFT JOIN `users` `u` ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL);", $select->build());
+    }
+
+    /**
+     * Test
+     *
+     * @covers ::crossJoinRaw
+     * @covers ::getJoinSql
+     * @covers ::from
+     * @covers ::prepare
+     * @covers ::build
+     */
+    public function testCrossJoinRaw()
+    {
+        $select = $this->select()
+            ->columns('id')
+            ->from('test')
+            ->crossJoinRaw('users u', new RawExp('t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL'));
+        $this->assertInstanceOf(PDOStatement::class, $select->prepare());
+        $this->assertSame("SELECT `id` FROM `test` CROSS JOIN `users` `u` ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c OR t2.b IS NULL);", $select->build());
+    }
+
     /**
      * Test
      *