RDBRelation generic

application/Espo/ORM/Repository/RDBRelation.php

@@ -31,6 +31,7 @@ namespace Espo\ORM\Repository;
 
 use Espo\ORM\Collection;
 use Espo\ORM\Entity;
+use Espo\ORM\EntityCollection;
 use Espo\ORM\EntityManager;
 use Espo\ORM\BaseEntity;
 use Espo\ORM\Query\Select;
@@ -47,6 +48,8 @@ use RuntimeException;
 
 /**
  * An access point for a specific relation of a record.
+ *
+ * @template TEntity of Entity
  */
 class RDBRelation
 {
@@ -93,6 +96,8 @@ class RDBRelation
 
     /**
      * Create a select builder.
+     *
+     * @return Builder<TEntity>
      */
     private function createSelectBuilder(?Select $query = null): Builder
     {
@@ -100,11 +105,14 @@ class RDBRelation
             throw new RuntimeException("Can't use query builder for the '$this->relationType' relation type.");
         }
 
+        /** @var Builder<TEntity> */
         return new Builder($this->entityManager, $this->entity, $this->relationName, $query);
     }
 
     /**
      * Clone a query.
+     *
+     * @return Builder<TEntity>
      */
     public function clone(Select $query): Builder
     {
@@ -116,6 +124,7 @@ class RDBRelation
             throw new RuntimeException("Passed query doesn't match the entity type.");
         }
 
+        /** @var Builder<TEntity> */
         return $this->createSelectBuilder($query);
     }
 
@@ -139,11 +148,12 @@ class RDBRelation
     /**
      * Find related records.
      *
-     * @return Collection<Entity>
+     * @return Collection<TEntity>
      */
     public function find(): Collection
     {
         if ($this->isBelongsToParentType()) {
+            /** @var EntityCollection<TEntity> $collection */
             $collection = $this->entityManager->getCollectionFactory()->create();
 
             $entity = $this->getMapper()->selectRelated($this->entity, $this->relationName);
@@ -162,6 +172,8 @@ class RDBRelation
 
     /**
      * Find a first record.
+     *
+     * @return TEntity
      */
     public function findOne(): ?Entity
     {
@@ -172,6 +184,7 @@ class RDBRelation
                 throw new LogicException();
             }
 
+            /** @var TEntity */
             return $entity;
         }
 
@@ -202,6 +215,7 @@ class RDBRelation
      * 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 Builder<TEntity>
      */
     public function join($target, ?string $alias = null, $conditions = null): Builder
     {
@@ -215,6 +229,7 @@ class RDBRelation
      * 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 Builder<TEntity>
      */
     public function leftJoin($target, ?string $alias = null, $conditions = null): Builder
     {
@@ -223,6 +238,8 @@ class RDBRelation
 
     /**
      * Set DISTINCT parameter.
+     *
+     * @return Builder<TEntity>
      */
     public function distinct(): Builder
     {
@@ -231,6 +248,8 @@ class RDBRelation
 
     /**
      * Set to return STH collection. Recommended for fetching large number of records.
+     *
+     * @return Builder<TEntity>
      */
     public function sth(): Builder
     {
@@ -247,6 +266,7 @@ class RDBRelation
      *
      * @param WhereItem|array<string|int, 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 Builder<TEntity>
      */
     public function where($clause = [], $value = null): Builder
     {
@@ -263,6 +283,7 @@ class RDBRelation
      *
      * @param WhereItem|array<string|int, 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 Builder<TEntity>
      */
     public function having($clause = [], $value = null): Builder
     {
@@ -282,6 +303,7 @@ class RDBRelation
      *   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 A direction.
+     * @return Builder<TEntity>
      */
     public function order($orderBy = 'id', $direction = null): Builder
     {
@@ -290,6 +312,8 @@ class RDBRelation
 
     /**
      * Apply OFFSET and LIMIT.
+     *
+     * @return Builder<TEntity>
      */
     public function limit(?int $offset = null, ?int $limit = null): Builder
     {
@@ -309,6 +333,7 @@ class RDBRelation
      * @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 Builder<TEntity>
      */
     public function select($select = [], ?string $alias = null): Builder
     {
@@ -325,6 +350,7 @@ class RDBRelation
      * * `groupBy([$expr1, $expr2, ...])`
      *
      * @param Expression|Expression[]|string|string[] $groupBy
+     * @return Builder<TEntity>
      */
     public function group($groupBy): Builder
     {
@@ -334,6 +360,7 @@ class RDBRelation
     /**
      * @deprecated Use `group` method.
      * @param Expression|Expression[]|string|string[] $groupBy
+     * @return Builder<TEntity>
      */
     public function groupBy($groupBy): Builder
     {
@@ -347,6 +374,7 @@ class RDBRelation
      * `->columnsWhere(['column' => $value])`
      *
      * @param WhereItem|array<string|int, mixed> $clause Where clause.
+     * @return Builder<TEntity>
      */
     public function columnsWhere($clause): Builder
     {

application/Espo/ORM/Repository/RDBRelationSelectBuilder.php

@@ -30,6 +30,7 @@
 namespace Espo\ORM\Repository;
 
 use Espo\ORM\Collection;
+use Espo\ORM\EntityCollection;
 use Espo\ORM\Mapper\RDBMapper;
 use Espo\ORM\SthCollection;
 use Espo\ORM\Entity;
@@ -49,6 +50,8 @@ use InvalidArgumentException;
 
 /**
  * Builds select parameters for related records for RDB repository.
+ *
+ * @template TEntity of Entity
  */
 class RDBRelationSelectBuilder
 {
@@ -124,6 +127,7 @@ class RDBRelationSelectBuilder
      * `->columnsWhere(['column' => $value])`
      *
      * @param WhereItem|array<int|string, mixed> $clause Where clause.
+     * @return self<TEntity>
      */
     public function columnsWhere($clause): self
     {
@@ -182,7 +186,7 @@ class RDBRelationSelectBuilder
     /**
      * Find related records by a criteria.
      *
-     * @return Collection<Entity>
+     * @return Collection<TEntity>
      */
     public function find(): Collection
     {
@@ -191,9 +195,12 @@ class RDBRelationSelectBuilder
         $related = $this->getMapper()->selectRelated($this->entity, $this->relationName, $query);
 
         if ($related instanceof Collection) {
+            /** @var Collection<TEntity> $related */
+
             return $this->handleReturnCollection($related);
         }
 
+        /** @var EntityCollection<TEntity> $collection */
         $collection = $this->entityManager->getCollectionFactory()->create($this->foreignEntityType);
 
         $collection->setAsFetched();
@@ -207,6 +214,8 @@ class RDBRelationSelectBuilder
 
     /**
      * Find a first related records by a criteria.
+     *
+     * @return TEntity
      */
     public function findOne(): ?Entity
     {
@@ -236,6 +245,7 @@ class RDBRelationSelectBuilder
      * 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
     {
@@ -251,6 +261,7 @@ class RDBRelationSelectBuilder
      * 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
     {
@@ -261,6 +272,8 @@ class RDBRelationSelectBuilder
 
     /**
      * Set DISTINCT parameter.
+     *
+     * @return self<TEntity>
      */
     public function distinct(): self
     {
@@ -271,6 +284,8 @@ class RDBRelationSelectBuilder
 
     /**
      * Return STH collection. Recommended for fetching large number of records.
+     *
+     * @return self<TEntity>
      */
     public function sth(): self
     {
@@ -289,6 +304,7 @@ class RDBRelationSelectBuilder
      *
      * @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
     {
@@ -319,6 +335,7 @@ class RDBRelationSelectBuilder
      *
      * @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
     {
@@ -340,6 +357,7 @@ class RDBRelationSelectBuilder
      *   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 = 'id', $direction = null): self
     {
@@ -350,6 +368,8 @@ class RDBRelationSelectBuilder
 
     /**
      * Apply OFFSET and LIMIT.
+     *
+     * @return self<TEntity>
      */
     public function limit(?int $offset = null, ?int $limit = null): self
     {
@@ -371,6 +391,7 @@ class RDBRelationSelectBuilder
      * @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
     {
@@ -389,6 +410,7 @@ class RDBRelationSelectBuilder
      * * `groupBy([$expr1, $expr2, ...])`
      *
      * @param Expression|Expression[]|string|string[] $groupBy
+     * @return self<TEntity>
      */
     public function group($groupBy): self
     {
@@ -400,6 +422,7 @@ class RDBRelationSelectBuilder
     /**
      * @deprecated Use `group` method.
      * @param Expression|Expression[]|string|string[] $groupBy
+     * @return self<TEntity>
      */
     public function groupBy($groupBy): self
     {
@@ -472,8 +495,8 @@ class RDBRelationSelectBuilder
     }
 
     /**
-     * @param Collection<Entity> $collection
-     * @return Collection<Entity>
+     * @param Collection<TEntity> $collection
+     * @return Collection<TEntity>
      */
     private function handleReturnCollection(Collection $collection): Collection
     {
@@ -485,6 +508,7 @@ class RDBRelationSelectBuilder
             return $collection;
         }
 
+        /** @var Collection<TEntity> */
         return $this->entityManager->getCollectionFactory()->createFromSthCollection($collection);
     }
 

application/Espo/ORM/Repository/RDBRepository.php

@@ -199,6 +199,7 @@ class RDBRepository implements Repository
      * Get an access point for a specific relation of a record.
      *
      * @param TEntity $entity
+     * @return RDBRelation<Entity>
      */
     public function getRelation(Entity $entity, string $relationName): RDBRelation
     {