Initial commit

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

@@ -0,0 +1,300 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://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 Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\ORM\Query\Part;
+
+use Espo\ORM\Query\Part\Join\JoinType;
+use Espo\ORM\Query\Select;
+use LogicException;
+use RuntimeException;
+
+/**
+ * A join item. Immutable.
+ */
+class Join
+{
+    /** A table join. */
+    public const MODE_TABLE = 0;
+    /** A relation join. */
+    public const MODE_RELATION = 1;
+    /** A sub-query join. */
+    public const MODE_SUB_QUERY = 3;
+
+    private ?WhereItem $conditions = null;
+    private bool $onlyMiddle = false;
+    private bool $isLateral = false;
+    private ?JoinType $type = null;
+
+    private function __construct(
+        private string|Select $target,
+        private ?string $alias = null
+    ) {
+        if ($target === '' || $alias === '') {
+            throw new RuntimeException("Bad join.");
+        }
+    }
+
+    /**
+     * Get a join target. A relation name, table or sub-query.
+     * A relation name is in camelCase, a table is in CamelCase.
+     */
+    public function getTarget(): string|Select
+    {
+        return $this->target;
+    }
+
+    /**
+     * Get an alias.
+     */
+    public function getAlias(): ?string
+    {
+        return $this->alias;
+    }
+
+    /**
+     * Get join conditions.
+     */
+    public function getConditions(): ?WhereItem
+    {
+        return $this->conditions;
+    }
+
+    /**
+     * Is a sub-query join.
+     */
+    public function isSubQuery(): bool
+    {
+        return !is_string($this->target);
+    }
+
+    /**
+     * Is a table join.
+     */
+    public function isTable(): bool
+    {
+        return is_string($this->target) && $this->target[0] === ucfirst($this->target[0]);
+    }
+
+    /**
+     * Is a relation join.
+     */
+    public function isRelation(): bool
+    {
+        return !$this->isSubQuery() && !$this->isTable();
+    }
+
+    /**
+     * Get a join mode.
+     *
+     * @return self::MODE_TABLE|self::MODE_RELATION|self::MODE_SUB_QUERY
+     */
+    public function getMode(): int
+    {
+        if ($this->isSubQuery()) {
+            return self::MODE_SUB_QUERY;
+        }
+
+        if ($this->isRelation()) {
+            return self::MODE_RELATION;
+        }
+
+        return self::MODE_TABLE;
+    }
+
+    /**
+     * Is only middle table to be joined.
+     */
+    public function isOnlyMiddle(): bool
+    {
+        return $this->onlyMiddle;
+    }
+
+    /**
+     * Is LATERAL.
+     *
+     * @since 9.1.6
+     */
+    public function isLateral(): bool
+    {
+        return $this->isLateral;
+    }
+
+    /**
+     * Get a join type.
+     *
+     * @return JoinType|null
+     *
+     * @since 9.2.0
+     */
+    public function getType(): ?JoinType
+    {
+        return $this->type;
+    }
+
+    /**
+     * Create.
+     *
+     * @param string|Select $target
+     * A relation name, table or sub-query. A relation name should be in camelCase, a table in CamelCase.
+     * When joining a table or sub-query, conditions should be specified.
+     * When joining a relation, conditions will be applied automatically, additional conditions can
+     * be specified as well.
+     * @param ?string $alias An alias.
+     */
+    public static function create(string|Select $target, ?string $alias = null): self
+    {
+        return new self($target, $alias);
+    }
+
+    /**
+     * Create with a table target.
+     *
+     * @param string $table A table name. Should start with an upper case letter.
+     * @param ?string $alias An alias.
+     */
+    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.
+     *
+     * @param string $relation A relation name. Should start with a lower case letter.
+     * @param ?string $alias An alias.
+     */
+    public static function createWithRelationTarget(string $relation, ?string $alias = null): self
+    {
+        return self::create(lcfirst($relation), $alias);
+    }
+
+    /**
+     * Create with a sub-query.
+     *
+     * @param Select $subQuery A sub-query.
+     * @param string $alias An alias.
+     */
+    public static function createWithSubQuery(Select $subQuery, string $alias): self
+    {
+        return new self($subQuery, $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;
+    }
+
+    /**
+     * Join only middle table. For many-to-many relationships.
+     */
+    public function withOnlyMiddle(bool $onlyMiddle = true): self
+    {
+        if (!$this->isRelation()) {
+            throw new LogicException("Only-middle is compatible only with relation joins.");
+        }
+
+        $obj = clone $this;
+        $obj->onlyMiddle = $onlyMiddle;
+
+        return $obj;
+    }
+
+    /**
+     * With LATERAL. Only for a sub-query join.
+     *
+     * @since 9.1.6
+     */
+    public function withLateral(bool $isLateral = true): self
+    {
+        if (!$this->isSubQuery()) {
+            throw new LogicException("Lateral can be used only with sub-query joins.");
+        }
+
+        $obj = clone $this;
+        $obj->isLateral = $isLateral;
+
+        return $obj;
+    }
+
+    /**
+     * With LEFT type.
+     *
+     * @since 9.2.0.
+     */
+    public function withLeft(): self
+    {
+        $obj = clone $this;
+        $obj->type = JoinType::left;
+
+        return $obj;
+    }
+
+    /**
+     * With INNER type.
+     *
+     * @since 9.2.0.
+     */
+    public function withInner(): self
+    {
+        $obj = clone $this;
+        $obj->type = JoinType::inner;
+
+        return $obj;
+    }
+
+    /**
+     * With a join type.
+     *
+     * @since 9.2.0.
+     */
+    public function withType(JoinType $type): self
+    {
+        $obj = clone $this;
+        $obj->type = $type;
+
+        return $obj;
+    }
+}