bsiggel
127fa6503b
- Updated copyright headers in 3,055 core application files - Changed 'Copyright (C) 2014-2025' to 'Copyright (C) 2014-2026' - Added 123 new files from EspoCRM core updates - Removed 4 deprecated files - Total changes: 61,637 insertions, 54,283 deletions This is a routine maintenance update for the new year 2026.
301 lines
7.5 KiB
PHP
301 lines
7.5 KiB
PHP
<?php
|
||
/************************************************************************
|
||
* This file is part of EspoCRM.
|
||
*
|
||
* EspoCRM – Open Source CRM application.
|
||
* Copyright (C) 2014-2026 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;
|
||
}
|
||
}
|