orm refactoring join class

application/Espo/ORM/Query/Part/Join.php

@@ -0,0 +1,137 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM - Open Source CRM application.
+ * Copyright (C) 2014-2021 Yurii Kuznietsov, Taras Machyshyn, Oleksii Avramenko
+ * Website: https://www.espocrm.com
+ *
+ * EspoCRM is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * EspoCRM is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with EspoCRM. If not, see http://www.gnu.org/licenses/.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\ORM\Query\Part;
+
+use RuntimeException;
+
+class Join
+{
+    private $target;
+
+    private $alias = null;
+
+    private $conditions = null;
+
+    private function __construct(string $target, ?string $alias = null)
+    {
+        $this->target = $target;
+        $this->alias = $alias;
+
+        if ($target === '' || $alias === '') {
+            throw new RuntimeException("Bad join.");
+        }
+    }
+
+    /**
+     * Get a join target. A relationName or table.
+     * A relationName is in camelCase, a table is in CamelCase.
+     */
+    public function getTarget(): string
+    {
+        return $this->target;
+    }
+
+    /**
+     * Get an alias.
+     */
+    public function getAlias(): ?string
+    {
+        return $this->alias;
+    }
+
+    /**
+     * Get join conditions.
+     */
+    public function getConditions(): ?WhereItem
+    {
+        return $this->conditions;
+    }
+
+    public function isTable(): bool
+    {
+        return $this->target[0] === ucfirst($this->target[0]);
+    }
+
+    public function isRelation(): bool
+    {
+        return !$this->isTable();
+    }
+
+    /**
+     * Create.
+     *
+     * @param string $target
+     * A relation name or table. A relationName should be in camelCase, a table in CamelCase.
+     * When joining a table, conditions should be specified.
+     * When joining a relation, conditions will be applied automatically.
+     */
+    public static function create(string $target, ?string $alias = null): self
+    {
+        return new self($target, $alias);
+    }
+
+    /**
+     * Create with a table target.
+     */
+    public static function createWithTableTarget(string $table, ?string $alias = null): self
+    {
+        return self::create(ucfirst($table), $alias);
+    }
+
+    /**
+     * Create with a relation target. Conditions will be applied automatically.
+     */
+    public static function createWithRelationTarget(string $relation, ?string $alias = null): self
+    {
+        return self::create(lcfirst($relation), $alias);
+    }
+
+    /**
+     * Clone with an alias.
+     */
+    public function withAlias(?string $alias): self
+    {
+        $obj = clone $this;
+        $obj->alias = $alias;
+
+        return $obj;
+    }
+
+    /**
+     * Clone with join conditions.
+     */
+    public function withConditions(?WhereItem $conditions): self
+    {
+        $obj = clone $this;
+        $obj->conditions = $conditions;
+
+        return $obj;
+    }
+}

application/Espo/ORM/Query/Part/SelectExpression.php

@@ -35,7 +35,7 @@ class SelectExpression
 
     private $alias = null;
 
-    public function __construct(Expression $expression, ?string $alias = null)
+    private function __construct(Expression $expression, ?string $alias = null)
     {
         $this->expression = $expression;
         $this->alias = $alias;

application/Espo/ORM/Query/SelectingBuilderTrait.php

@@ -32,6 +32,7 @@ namespace Espo\ORM\Query;
 use Espo\ORM\Query\Part\WhereItem;
 use Espo\ORM\Query\Part\Expression;
 use Espo\ORM\Query\Part\OrderExpression;
+use Espo\ORM\Query\Part\Join;
 
 use InvalidArgumentException;
 
@@ -152,13 +153,19 @@ trait SelectingBuilderTrait
     /**
      * Add JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function join($relationName, ?string $alias = null, $conditions = null): self
+    public function join($target, ?string $alias = null, $conditions = null): self
     {
+        if ($target instanceof Join) {
+            $alias = $alias ?? $target->getAlias();
+            $conditions = $conditions ?? $target->getConditions();
+            $target = $target->getTarget();
+        }
+
         if ($conditions !== null && !is_array($conditions) && !$conditions instanceof WhereItem) {
             throw new InvalidArgumentException("Conditions must be WhereItem or array.");
         }
@@ -171,8 +178,8 @@ trait SelectingBuilderTrait
             $this->params['joins'] = [];
         }
 
-        if (is_array($relationName)) {
-            $joinList = $relationName;
+        if (is_array($target)) {
+            $joinList = $target;
 
             foreach ($joinList as $item) {
                 $this->params['joins'][] = $item;
@@ -181,23 +188,23 @@ trait SelectingBuilderTrait
             return $this;
         }
 
-        if (is_null($alias) && is_null($conditions) && $this->hasJoinAlias($relationName)) {
+        if (is_null($alias) && is_null($conditions) && $this->hasJoinAlias($target)) {
             return $this;
         }
 
         if (is_null($alias) && is_null($conditions)) {
-            $this->params['joins'][] = $relationName;
+            $this->params['joins'][] = $target;
 
             return $this;
         }
 
         if (is_null($conditions)) {
-            $this->params['joins'][] = [$relationName, $alias];
+            $this->params['joins'][] = [$target, $alias];
 
             return $this;
         }
 
-        $this->params['joins'][] = [$relationName, $alias, $conditions];
+        $this->params['joins'][] = [$target, $alias, $conditions];
 
         return $this;
     }
@@ -205,13 +212,19 @@ trait SelectingBuilderTrait
     /**
      * Add LEFT JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function leftJoin($relationName, ?string $alias = null, $conditions = null): self
+    public function leftJoin($target, ?string $alias = null, $conditions = null): self
     {
+        if ($target instanceof Join) {
+            $alias = $alias ?? $target->getAlias();
+            $conditions = $conditions ?? $target->getConditions();
+            $target = $target->getTarget();
+        }
+
         if ($conditions !== null && !is_array($conditions) && !$conditions instanceof WhereItem) {
             throw new InvalidArgumentException("Conditions must be WhereItem or array.");
         }
@@ -224,8 +237,8 @@ trait SelectingBuilderTrait
             $this->params['leftJoins'] = [];
         }
 
-        if (is_array($relationName)) {
-            $joinList = $relationName;
+        if (is_array($target)) {
+            $joinList = $target;
 
             foreach ($joinList as $item) {
                 $this->params['leftJoins'][] = $item;
@@ -234,23 +247,23 @@ trait SelectingBuilderTrait
             return $this;
         }
 
-        if (is_null($alias) && is_null($conditions) && $this->hasLeftJoinAlias($relationName)) {
+        if (is_null($alias) && is_null($conditions) && $this->hasLeftJoinAlias($target)) {
             return $this;
         }
 
         if (is_null($alias) && is_null($conditions)) {
-            $this->params['leftJoins'][] = $relationName;
+            $this->params['leftJoins'][] = $target;
 
             return $this;
         }
 
         if (is_null($conditions)) {
-            $this->params['leftJoins'][] = [$relationName, $alias];
+            $this->params['leftJoins'][] = [$target, $alias];
 
             return $this;
         }
 
-        $this->params['leftJoins'][] = [$relationName, $alias, $conditions];
+        $this->params['leftJoins'][] = [$target, $alias, $conditions];
 
         return $this;
     }

application/Espo/ORM/Query/SelectingTrait.php

@@ -31,6 +31,7 @@ namespace Espo\ORM\Query;
 
 use Espo\ORM\Query\Part\OrderExpression;
 use Espo\ORM\Query\Part\WhereClause;
+use Espo\ORM\Query\Part\Join;
 
 use RuntimeException;
 
@@ -76,6 +77,48 @@ trait SelectingTrait
         return WhereClause::fromRaw($whereClause);
     }
 
+    /**
+     * Get JOIN items.
+     *
+     * @return Join[]
+     */
+    public function getJoins(): array
+    {
+        return array_map(
+            function ($item) {
+                $conditions = isset($item[2]) ?
+                    WhereClause::fromRaw($item[2]) :
+                    null;
+
+                return Join::create($item[0])
+                    ->withAlias($item[1] ?? null)
+                    ->withConditions($conditions);
+            },
+            $this->params['joins'] ?? []
+        );
+    }
+
+    /**
+     * Get LEFT JOIN items.
+     *
+     * @return Join[]
+     */
+    public function getLeftJoins(): array
+    {
+        return array_map(
+            function ($item) {
+                $conditions = isset($item[2]) ?
+                    WhereClause::fromRaw($item[2]) :
+                    null;
+
+                return Join::create($item[0])
+                    ->withAlias($item[1] ?? null)
+                    ->withConditions($conditions);
+            },
+            $this->params['leftJoins'] ?? []
+        );
+    }
+
     private static function validateRawParamsSelecting(array $params): void
     {
     }

application/Espo/ORM/Repository/RDBRelation.php

@@ -36,6 +36,7 @@ use Espo\ORM\{
     Query\Select,
     Query\Part\WhereItem,
     Query\Part\SelectExpression,
+    Query\Part\Join,
     Mapper\RDBMapper,
     Repository\RDBRelationSelectBuilder as Builder,
 };
@@ -185,27 +186,27 @@ class RDBRelation
     /**
      * Add JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function join(string $relationName, ?string $alias = null, $conditions = null): Builder
+    public function join(string $target, ?string $alias = null, $conditions = null): Builder
     {
-        return $this->createSelectBuilder()->join($relationName, $alias, $conditions);
+        return $this->createSelectBuilder()->join($target, $alias, $conditions);
     }
 
     /**
      * Add LEFT JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function leftJoin(string $relationName, ?string $alias = null, $conditions = null): Builder
+    public function leftJoin(string $target, ?string $alias = null, $conditions = null): Builder
     {
-        return $this->createSelectBuilder()->leftJoin($relationName, $alias, $conditions);
+        return $this->createSelectBuilder()->leftJoin($target, $alias, $conditions);
     }
 
     /**

application/Espo/ORM/Repository/RDBRelationSelectBuilder.php

@@ -38,6 +38,7 @@ use Espo\ORM\{
     Query\SelectBuilder,
     Query\Part\WhereItem,
     Query\Part\SelectExpression,
+    Query\Part\Join,
     Mapper\Mapper,
 };
 
@@ -238,14 +239,14 @@ class RDBRelationSelectBuilder
     /**
      * Add JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function join($relationName, ?string $alias = null, $conditions = null): self
+    public function join($target, ?string $alias = null, $conditions = null): self
     {
-        $this->builder->join($relationName, $alias, $conditions);
+        $this->builder->join($target, $alias, $conditions);
 
         return $this;
     }
@@ -253,14 +254,14 @@ class RDBRelationSelectBuilder
     /**
      * Add LEFT JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function leftJoin($relationName, ?string $alias = null, $conditions = null): self
+    public function leftJoin($target, ?string $alias = null, $conditions = null): self
     {
-        $this->builder->leftJoin($relationName, $alias, $conditions);
+        $this->builder->leftJoin($target, $alias, $conditions);
 
         return $this;
     }

application/Espo/ORM/Repository/RDBRepository.php

@@ -39,6 +39,7 @@ use Espo\ORM\{
     Query\Select,
     Query\Part\WhereItem,
     Query\Part\SelectExpression,
+    Query\Part\Join,
 };
 
 use StdClass;
@@ -673,27 +674,27 @@ class RDBRepository extends Repository
     /**
      * Add JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function join($relationName, ?string $alias = null, $conditions = null): RDBSelectBuilder
+    public function join($target, ?string $alias = null, $conditions = null): RDBSelectBuilder
     {
-        return $this->createSelectBuilder()->join($relationName, $alias, $conditions);
+        return $this->createSelectBuilder()->join($target, $alias, $conditions);
     }
 
     /**
      * Add LEFT JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function leftJoin($relationName, ?string $alias = null, $conditions = null): RDBSelectBuilder
+    public function leftJoin($target, ?string $alias = null, $conditions = null): RDBSelectBuilder
     {
-        return $this->createSelectBuilder()->leftJoin($relationName, $alias, $conditions);
+        return $this->createSelectBuilder()->leftJoin($target, $alias, $conditions);
     }
 
     /**

application/Espo/ORM/Repository/RDBSelectBuilder.php

@@ -38,6 +38,7 @@ use Espo\ORM\{
     Query\SelectBuilder,
     Query\Part\WhereItem,
     Query\Part\SelectExpression,
+    Query\Part\Join,
     Mapper\Mapper,
 };
 
@@ -175,14 +176,14 @@ class RDBSelectBuilder
     /**
      * Add JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function join($relationName, ?string $alias = null, $conditions = null): self
+    public function join($target, ?string $alias = null, $conditions = null): self
     {
-        $this->builder->join($relationName, $alias, $conditions);
+        $this->builder->join($target, $alias, $conditions);
 
         return $this;
     }
@@ -190,14 +191,14 @@ class RDBSelectBuilder
     /**
      * Add LEFT JOIN.
      *
-     * @param string $relationName
-     *     A relationName or table. A relationName is in camelCase, a table is in CamelCase.
+     * @param Join|string $target
+     * A relation name or table. A relation name should be in camelCase, a table in CamelCase.
      * @param string|null $alias An alias.
      * @param WhereItem|array|null $conditions Join conditions.
      */
-    public function leftJoin($relationName, ?string $alias = null, $conditions = null): self
+    public function leftJoin($target, ?string $alias = null, $conditions = null): self
     {
-        $this->builder->leftJoin($relationName, $alias, $conditions);
+        $this->builder->leftJoin($target, $alias, $conditions);
 
         return $this;
     }

tests/unit/Espo/ORM/Query/Parts/JoinTest.php

@@ -0,0 +1,80 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM - Open Source CRM application.
+ * Copyright (C) 2014-2021 Yurii Kuznietsov, Taras Machyshyn, Oleksii Avramenko
+ * Website: https://www.espocrm.com
+ *
+ * EspoCRM is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * EspoCRM is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with EspoCRM. If not, see http://www.gnu.org/licenses/.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace tests\unit\Espo\ORM\Query\Part;
+
+use Espo\ORM\Query\Part\Join;
+use Espo\ORM\Query\Part\Expression as Expr;
+
+class JoinTest extends \PHPUnit\Framework\TestCase
+{
+    public function testCreate1(): void
+    {
+        $conditions = Expr::isNull(
+            Expr::column('test')
+        );
+
+        $join = Join::createWithRelationTarget('test')
+            ->withAlias('testAlias')
+            ->withConditions($conditions);
+
+        $this->assertEquals('test', $join->getTarget());
+        $this->assertEquals('testAlias', $join->getAlias());
+        $this->assertEquals($conditions, $join->getConditions());
+
+        $this->assertTrue($join->isRelation());
+        $this->assertFalse($join->isTable());
+    }
+
+    public function testCreate2(): void
+    {
+        $conditions = Expr::isNull(
+            Expr::column('test')
+        );
+
+        $join = Join::createWithTableTarget('Test')
+            ->withAlias('testAlias')
+            ->withConditions($conditions);
+
+        $this->assertEquals('Test', $join->getTarget());
+        $this->assertEquals('testAlias', $join->getAlias());
+        $this->assertEquals($conditions, $join->getConditions());
+
+        $this->assertTrue($join->isTable());
+        $this->assertFalse($join->isRelation());
+    }
+
+    public function testCreate3(): void
+    {
+        $join = Join::create('Test', 'testAlias');
+
+        $this->assertEquals('Test', $join->getTarget());
+        $this->assertEquals('testAlias', $join->getAlias());
+    }
+}

tests/unit/Espo/ORM/Query/SelectBuilderTest.php

@@ -35,6 +35,8 @@ use Espo\ORM\{
     Query\Part\Expression as Expr,
     Query\Part\SelectExpression,
     Query\Part\OrderExpression,
+    Query\Part\Join,
+    Query\Part\WhereClause,
 };
 
 class SelectBuilderTest extends \PHPUnit\Framework\TestCase
@@ -473,7 +475,7 @@ class SelectBuilderTest extends \PHPUnit\Framework\TestCase
         $this->assertEquals($expected, $raw['whereClause']);
     }
 
-    public function testLeftJoin()
+    public function testLeftJoin1()
     {
         $params = $this->builder
             ->from('Test')
@@ -486,7 +488,50 @@ class SelectBuilderTest extends \PHPUnit\Framework\TestCase
         $this->assertEquals(['link1', 'link2'], $params['leftJoins']);
     }
 
-    public function testJoin()
+    public function testLeftJoin2()
+    {
+        $query = $this->builder
+            ->from('Test')
+            ->leftJoin('link1', 'alias1', ['name' => 'test'])
+            ->leftJoin('link2', 'alias2')
+            ->build();
+
+        $this->assertEquals(
+            [
+                Join::create('link1', 'alias1')
+                    ->withConditions(WhereClause::fromRaw(['name' => 'test'])),
+                Join::create('link2', 'alias2'),
+            ],
+            $query->getLeftJoins()
+        );
+    }
+
+    public function testLeftJoin3()
+    {
+        $query = $this->builder
+            ->from('Test')
+            ->leftJoin(
+                Join::create('link1', 'alias1')
+                    ->withConditions(
+                        WhereClause::fromRaw(['name' => 'test'])
+                    )
+            )
+            ->leftJoin(
+                Join::create('link2', 'alias2')
+            )
+            ->build();
+
+        $this->assertEquals(
+            [
+                Join::create('link1', 'alias1')
+                    ->withConditions(WhereClause::fromRaw(['name' => 'test'])),
+                Join::create('link2', 'alias2'),
+            ],
+            $query->getLeftJoins()
+        );
+    }
+
+    public function testJoin1()
     {
         $params = $this->builder
             ->from('Test')
@@ -499,6 +544,45 @@ class SelectBuilderTest extends \PHPUnit\Framework\TestCase
         $this->assertEquals(['link1', 'link2'], $params['joins']);
     }
 
+    public function testJoin2()
+    {
+        $query = $this->builder
+            ->from('Test')
+            ->join('link1', 'alias1', ['name' => 'test'])
+            ->join('link2', 'alias2')
+            ->build();
+
+        $this->assertEquals(
+            [
+                Join::create('link1', 'alias1')
+                    ->withConditions(WhereClause::fromRaw(['name' => 'test'])),
+                Join::create('link2', 'alias2'),
+            ],
+            $query->getJoins()
+        );
+    }
+
+    public function testJoin3()
+    {
+        $query = $this->builder
+            ->from('Test')
+            ->join(
+                Join::create('link1', 'alias1')
+                    ->withConditions(WhereClause::fromRaw(['name' => 'test']))
+            )
+            ->join(Join::create('link2', 'alias2'))
+            ->build();
+
+        $this->assertEquals(
+            [
+                Join::create('link1', 'alias1')
+                    ->withConditions(WhereClause::fromRaw(['name' => 'test'])),
+                Join::create('link2', 'alias2'),
+            ],
+            $query->getJoins()
+        );
+    }
+
     public function testWhereItemUsage1()
     {
         $query = $this->builder