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.
548 lines
16 KiB
PHP
548 lines
16 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\Repository;
|
||
|
||
use Espo\ORM\Collection;
|
||
use Espo\ORM\Defs\Params\RelationParam;
|
||
use Espo\ORM\EntityCollection;
|
||
use Espo\ORM\Mapper\RDBMapper;
|
||
use Espo\ORM\Name\Attribute;
|
||
use Espo\ORM\SthCollection;
|
||
use Espo\ORM\Entity;
|
||
use Espo\ORM\EntityManager;
|
||
use Espo\ORM\BaseEntity;
|
||
use Espo\ORM\Query\Select;
|
||
use Espo\ORM\Query\SelectBuilder;
|
||
use Espo\ORM\Query\Part\WhereItem;
|
||
use Espo\ORM\Query\Part\Selection;
|
||
use Espo\ORM\Query\Part\Join;
|
||
use Espo\ORM\Query\Part\Expression;
|
||
use Espo\ORM\Query\Part\Order;
|
||
|
||
use LogicException;
|
||
use RuntimeException;
|
||
use InvalidArgumentException;
|
||
|
||
/**
|
||
* Builds select parameters for related records for RDB repository.
|
||
*
|
||
* @template TEntity of Entity = Entity
|
||
*/
|
||
class RDBRelationSelectBuilder
|
||
{
|
||
private string $foreignEntityType;
|
||
private ?string $relationType;
|
||
private SelectBuilder $builder;
|
||
private ?string $middleTableAlias = null;
|
||
private bool $returnSthCollection = false;
|
||
|
||
public function __construct(
|
||
private EntityManager $entityManager,
|
||
private Entity $entity,
|
||
private string $relationName,
|
||
?Select $query = null
|
||
) {
|
||
$this->relationType = $entity->getRelationType($relationName);
|
||
$entityType = $entity->getEntityType();
|
||
|
||
if ($entity instanceof BaseEntity) {
|
||
$this->foreignEntityType = $entity->getRelationParam($relationName, RelationParam::ENTITY);
|
||
} else {
|
||
$this->foreignEntityType = $this->entityManager
|
||
->getDefs()
|
||
->getEntity($entityType)
|
||
->getRelation($relationName)
|
||
->getForeignEntityType();
|
||
}
|
||
|
||
$this->builder = $query ?
|
||
$this->cloneQueryToBuilder($query) :
|
||
$this->createSelectBuilder()->from($this->foreignEntityType);
|
||
}
|
||
|
||
private function cloneQueryToBuilder(Select $query): SelectBuilder
|
||
{
|
||
$where = $query->getWhere();
|
||
|
||
if ($where === null) {
|
||
return $this->createSelectBuilder()->clone($query);
|
||
}
|
||
|
||
$rawQuery = $query->getRaw();
|
||
|
||
$rawQuery['whereClause'] = $this->applyRelationAliasToWhereClause($where->getRaw());
|
||
|
||
$newQuery = Select::fromRaw($rawQuery);
|
||
|
||
return $this->createSelectBuilder()->clone($newQuery);
|
||
}
|
||
|
||
private function createSelectBuilder(): SelectBuilder
|
||
{
|
||
return new SelectBuilder();
|
||
}
|
||
|
||
private function getMapper(): RDBMapper
|
||
{
|
||
$mapper = $this->entityManager->getMapper();
|
||
|
||
/** @noinspection PhpConditionAlreadyCheckedInspection */
|
||
if (!$mapper instanceof RDBMapper) {
|
||
throw new LogicException();
|
||
}
|
||
|
||
return $mapper;
|
||
}
|
||
|
||
/**
|
||
* Apply middle table conditions for a many-to-many relationship.
|
||
*
|
||
* Usage example:
|
||
* `->columnsWhere(['column' => $value])`
|
||
*
|
||
* @param WhereItem|array<int|string, mixed> $clause Where clause.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function columnsWhere($clause): self
|
||
{
|
||
if ($this->relationType !== Entity::MANY_MANY) {
|
||
throw new RuntimeException("Can't add columns where for not many-to-many relationship.");
|
||
}
|
||
|
||
if ($clause instanceof WhereItem) {
|
||
$clause = $clause->getRaw();
|
||
}
|
||
|
||
if (!is_array($clause)) {
|
||
throw new InvalidArgumentException();
|
||
}
|
||
|
||
$transformedWhere = $this->applyMiddleAliasToWhere($clause);
|
||
|
||
$this->where($transformedWhere);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* @param array<string|int, mixed> $where
|
||
* @return array<string|int, mixed>
|
||
*/
|
||
private function applyMiddleAliasToWhere(array $where): array
|
||
{
|
||
$transformedWhere = [];
|
||
|
||
$middleName = lcfirst($this->getRelationParam(RelationParam::RELATION_NAME));
|
||
|
||
foreach ($where as $key => $value) {
|
||
$transformedKey = $key;
|
||
$transformedValue = $value;
|
||
|
||
if (
|
||
is_string($key) &&
|
||
strlen($key) &&
|
||
!str_contains($key, '.') &&
|
||
$key[0] === strtolower($key[0])
|
||
) {
|
||
$transformedKey = $middleName . '.' . $key;
|
||
}
|
||
|
||
if (is_array($value)) {
|
||
$transformedValue = $this->applyMiddleAliasToWhere($value);
|
||
}
|
||
|
||
$transformedWhere[$transformedKey] = $transformedValue;
|
||
}
|
||
|
||
return $transformedWhere;
|
||
}
|
||
|
||
/**
|
||
* Find related records by a criteria.
|
||
*
|
||
* @return EntityCollection<TEntity>|SthCollection<TEntity>
|
||
*/
|
||
public function find(): EntityCollection|SthCollection
|
||
{
|
||
$query = $this->builder->build();
|
||
|
||
$related = $this->getMapper()->selectRelated($this->entity, $this->relationName, $query);
|
||
|
||
if ($related instanceof Collection) {
|
||
/** @var Collection<TEntity> $related */
|
||
|
||
/** @var EntityCollection<TEntity>|SthCollection<TEntity> */
|
||
return $this->handleReturnCollection($related);
|
||
}
|
||
|
||
/** @var EntityCollection<TEntity> $collection */
|
||
$collection = $this->entityManager->getCollectionFactory()->create($this->foreignEntityType);
|
||
|
||
$collection->setAsFetched();
|
||
|
||
if ($related instanceof Entity) {
|
||
$collection[] = $related;
|
||
}
|
||
|
||
return $collection;
|
||
}
|
||
|
||
/**
|
||
* Find a first related records by a criteria.
|
||
*
|
||
* @return TEntity
|
||
*/
|
||
public function findOne(): ?Entity
|
||
{
|
||
$queryTemp = $this->builder->build();
|
||
|
||
$returnSthCollection = $this->returnSthCollection;
|
||
$offset = $queryTemp->getOffset();
|
||
$limit = $queryTemp->getLimit();
|
||
|
||
$collection = $this
|
||
->sth()
|
||
->limit(0, 1)
|
||
->find();
|
||
|
||
$this->returnSthCollection = $returnSthCollection;
|
||
$this->limit($offset, $limit);
|
||
|
||
foreach ($collection as $entity) {
|
||
return $entity;
|
||
}
|
||
|
||
return null;
|
||
}
|
||
|
||
/**
|
||
* Get a number of related records that meet criteria.
|
||
*/
|
||
public function count(): int
|
||
{
|
||
$query = $this->builder->build();
|
||
|
||
return $this->getMapper()->countRelated($this->entity, $this->relationName, $query);
|
||
}
|
||
|
||
/**
|
||
* Add JOIN.
|
||
*
|
||
* @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<string|int, mixed>|null $conditions Join conditions.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function join($target, ?string $alias = null, $conditions = null): self
|
||
{
|
||
$this->builder->join($target, $alias, $conditions);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Add LEFT JOIN.
|
||
*
|
||
* @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<int|string, mixed>|null $conditions Join conditions.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function leftJoin($target, ?string $alias = null, $conditions = null): self
|
||
{
|
||
$this->builder->leftJoin($target, $alias, $conditions);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Set DISTINCT parameter.
|
||
*
|
||
* @return self<TEntity>
|
||
*/
|
||
public function distinct(): self
|
||
{
|
||
$this->builder->distinct();
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Return STH collection. Recommended for fetching large number of records.
|
||
*
|
||
* @return self<TEntity>
|
||
*/
|
||
public function sth(): self
|
||
{
|
||
$this->returnSthCollection = true;
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Add a WHERE clause.
|
||
*
|
||
* Usage options:
|
||
* * `where(WhereItem $clause)`
|
||
* * `where(array $clause)`
|
||
* * `where(string $key, string $value)`
|
||
*
|
||
* @param WhereItem|array<int|string, mixed>|string $clause A key or where clause.
|
||
* @param array<int, mixed>|scalar|null $value A value. Should be omitted if the first argument is not string.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function where($clause = [], $value = null): self
|
||
{
|
||
if ($this->isManyMany()) {
|
||
if ($clause instanceof WhereItem) {
|
||
$clause = $this->applyRelationAliasToWhereClause($clause->getRaw());
|
||
} else if (is_string($clause)) {
|
||
$clause = $this->applyRelationAliasToWhereClauseKey($clause);
|
||
} else if (is_array($clause)) {
|
||
$clause = $this->applyRelationAliasToWhereClause($clause);
|
||
}
|
||
}
|
||
|
||
$this->builder->where($clause, $value);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Add a HAVING clause.
|
||
*
|
||
* Usage options:
|
||
* * `having(WhereItem $clause)`
|
||
* * `having(array $clause)`
|
||
* * `having(string $key, string $value)`
|
||
*
|
||
* @param WhereItem|array<int|string, mixed>|string $clause A key or where clause.
|
||
* @param array<int, mixed>|string|null $value A value. Should be omitted if the first argument is not string.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function having($clause = [], $value = null): self
|
||
{
|
||
$this->builder->having($clause, $value);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Apply ORDER. Passing an array will override previously set items.
|
||
* Passing non-array will append an item,
|
||
*
|
||
* Usage options:
|
||
* * `order(Order $expression)
|
||
* * `order([$expr1, $expr2, ...])
|
||
* * `order(string $expression, string $direction)
|
||
*
|
||
* @param Order|Order[]|Expression|string|array<int, string[]>|string[] $orderBy
|
||
* An attribute to order by or an array or order items.
|
||
* Passing an array will reset a previously set order.
|
||
* @param (Order::ASC|Order::DESC)|bool|null $direction Select::ORDER_ASC|Select::ORDER_DESC.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function order($orderBy = Attribute::ID, $direction = null): self
|
||
{
|
||
$this->builder->order($orderBy, $direction);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Apply OFFSET and LIMIT.
|
||
*
|
||
* @return self<TEntity>
|
||
*/
|
||
public function limit(?int $offset = null, ?int $limit = null): self
|
||
{
|
||
$this->builder->limit($offset, $limit);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Specify SELECT. Columns and expressions to be selected. If not called, then
|
||
* all entity attributes will be selected. Passing an array will reset
|
||
* previously set items. Passing a SelectExpression|Expression|string will append the item.
|
||
*
|
||
* Usage options:
|
||
* * `select(SelectExpression $expression)`
|
||
* * `select([$expr1, $expr2, ...])`
|
||
* * `select(string $expression, string $alias)`
|
||
*
|
||
* @param Selection|Selection[]|Expression|Expression[]|string[]|string|array<int, string[]|string> $select
|
||
* An array of expressions or one expression.
|
||
* @param string|null $alias An alias. Actual if the first parameter is not an array.
|
||
* @return self<TEntity>
|
||
*/
|
||
public function select($select, ?string $alias = null): self
|
||
{
|
||
$this->builder->select($select, $alias);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* Specify GROUP BY.
|
||
* Passing an array will reset previously set items.
|
||
* Passing a string|Expression will append an item.
|
||
*
|
||
* Usage options:
|
||
* * `groupBy(Expression|string $expression)`
|
||
* * `groupBy([$expr1, $expr2, ...])`
|
||
*
|
||
* @param Expression|Expression[]|string|string[] $groupBy
|
||
* @return self<TEntity>
|
||
*/
|
||
public function group($groupBy): self
|
||
{
|
||
$this->builder->group($groupBy);
|
||
|
||
return $this;
|
||
}
|
||
|
||
/**
|
||
* @deprecated Use `group` method.
|
||
* @param Expression|Expression[]|string|string[] $groupBy
|
||
* @return self<TEntity>
|
||
*/
|
||
public function groupBy($groupBy): self
|
||
{
|
||
return $this->group($groupBy);
|
||
}
|
||
|
||
private function getMiddleTableAlias(): ?string
|
||
{
|
||
if (!$this->isManyMany()) {
|
||
return null;
|
||
}
|
||
|
||
if (!$this->middleTableAlias) {
|
||
$middleName = $this->getRelationParam(RelationParam::RELATION_NAME);
|
||
|
||
if (!$middleName) {
|
||
throw new RuntimeException("No relation name.");
|
||
}
|
||
|
||
$this->middleTableAlias = lcfirst($middleName);
|
||
}
|
||
|
||
return $this->middleTableAlias;
|
||
}
|
||
|
||
private function applyRelationAliasToWhereClauseKey(string $item): string
|
||
{
|
||
if (!$this->isManyMany()) {
|
||
return $item;
|
||
}
|
||
|
||
$alias = $this->getMiddleTableAlias();
|
||
|
||
return str_replace('@relation.', $alias . '.', $item);
|
||
}
|
||
|
||
/**
|
||
* @param array<int|string, mixed> $where
|
||
* @return array<int|string, mixed>
|
||
*/
|
||
private function applyRelationAliasToWhereClause(array $where): array
|
||
{
|
||
if (!$this->isManyMany()) {
|
||
return $where;
|
||
}
|
||
|
||
$transformedWhere = [];
|
||
|
||
foreach ($where as $key => $value) {
|
||
$transformedKey = $key;
|
||
$transformedValue = $value;
|
||
|
||
if (is_string($key)) {
|
||
$transformedKey = $this->applyRelationAliasToWhereClauseKey($key);
|
||
}
|
||
|
||
if (is_array($value)) {
|
||
$transformedValue = $this->applyRelationAliasToWhereClause($value);
|
||
}
|
||
|
||
$transformedWhere[$transformedKey] = $transformedValue;
|
||
}
|
||
|
||
return $transformedWhere;
|
||
}
|
||
|
||
private function isManyMany(): bool
|
||
{
|
||
return $this->relationType === Entity::MANY_MANY;
|
||
}
|
||
|
||
/**
|
||
* @param Collection<TEntity> $collection
|
||
* @return Collection<TEntity>
|
||
*/
|
||
private function handleReturnCollection(Collection $collection): Collection
|
||
{
|
||
if (!$collection instanceof SthCollection) {
|
||
return $collection;
|
||
}
|
||
|
||
if ($this->returnSthCollection) {
|
||
return $collection;
|
||
}
|
||
|
||
/** @var Collection<TEntity> */
|
||
return $this->entityManager->getCollectionFactory()->createFromSthCollection($collection);
|
||
}
|
||
|
||
/**
|
||
* @return mixed
|
||
* @noinspection PhpSameParameterValueInspection
|
||
*/
|
||
private function getRelationParam(string $param)
|
||
{
|
||
if ($this->entity instanceof BaseEntity) {
|
||
return $this->entity->getRelationParam($this->relationName, $param);
|
||
}
|
||
|
||
$entityDefs = $this->entityManager
|
||
->getDefs()
|
||
->getEntity($this->entity->getEntityType());
|
||
|
||
if (!$entityDefs->hasRelation($this->relationName)) {
|
||
return null;
|
||
}
|
||
|
||
return $entityDefs->getRelation($this->relationName)->getParam($param);
|
||
}
|
||
}
|