From 6f1c9d84822ea3369b9ffcd15a82fc40fa5490a0 Mon Sep 17 00:00:00 2001
From: Jan Skrasek <hrach.cz@gmail.com>
Date: Fri, 3 Jun 2022 21:19:37 +0200
Subject: [PATCH] relationships: implement generic HasMany & HasOne
 relationships

Latest PHPStorm 2022.2 EAP supports proper enumation of generic
Traverable, so completely migrating to HasMany<E> syntax.
---
 .idea/codeStyles/Project.xml                  |  2 +
 composer.json                                 |  4 +-
 src/Entity/Embeddable/EmbeddableContainer.php |  3 +
 src/Entity/IEntityAwareProperty.php           |  7 ++-
 src/Entity/Reflection/MetadataParser.php      |  1 +
 src/Relationships/HasMany.php                 | 58 +++++++++++++------
 src/Relationships/HasOne.php                  | 42 +++++++++++---
 src/Relationships/IRelationshipCollection.php | 15 ++++-
 src/Relationships/IRelationshipContainer.php  | 10 +++-
 src/Relationships/ManyHasMany.php             |  7 ++-
 src/Relationships/ManyHasOne.php              |  5 ++
 src/Relationships/OneHasMany.php              |  7 ++-
 src/Relationships/OneHasOne.php               |  6 +-
 src/Repository/IRepository.php                |  1 +
 src/Repository/PersistenceHelper.php          |  8 +--
 src/Repository/RemovalHelper.php              |  8 +--
 src/Repository/Repository.php                 |  2 -
 .../Relationships/entity.relationships.phpt   | 10 ++--
 .../relationships.HasManyCollection.phpt      |  2 +-
 .../relationships.manyHasMany.collection.phpt |  2 +-
 .../relationships.manyHasMany.phpt            |  8 +--
 .../relationships.oneHasMany.collection.phpt  |  2 +-
 tests/inc/model/author/Author.php             | 22 +++----
 tests/inc/model/book/Book.php                 |  4 +-
 tests/inc/model/contents/Thread.php           |  4 +-
 .../model/contents/ThreadCommentCommon.php    |  4 +-
 tests/inc/model/log/Log.php                   |  2 +-
 tests/inc/model/photoAlbum/PhotoAlbum.php     | 10 ++--
 tests/inc/model/publisher/Publisher.php       | 14 ++---
 tests/inc/model/tag/Tag.php                   | 14 ++---
 tests/inc/model/tagFollower/TagFollower.php   |  6 +-
 tests/inc/model/user/User.php                 |  8 +--
 32 files changed, 193 insertions(+), 105 deletions(-)

diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml
index d0b4672a..0ca00efa 100644
--- a/.idea/codeStyles/Project.xml
+++ b/.idea/codeStyles/Project.xml
@@ -3,6 +3,8 @@
     <option name="LINE_SEPARATOR" value="&#10;" />
     <option name="FORMATTER_TAGS_ENABLED" value="true" />
     <PHPCodeStyleSettings>
+      <option name="ALIGN_PHPDOC_PARAM_NAMES" value="true" />
+      <option name="ALIGN_PHPDOC_COMMENTS" value="true" />
       <option name="COMMA_AFTER_LAST_ARRAY_ELEMENT" value="true" />
       <option name="LOWER_CASE_BOOLEAN_CONST" value="true" />
       <option name="LOWER_CASE_NULL_CONST" value="true" />
diff --git a/composer.json b/composer.json
index 78295d53..1f824e68 100644
--- a/composer.json
+++ b/composer.json
@@ -36,7 +36,7 @@
 		"marc-mabe/php-enum": "~3.0",
 		"mockery/mockery": "~1.2",
 		"phpstan/extension-installer": "1.1.0",
-		"phpstan/phpstan": "1.4.10",
+		"phpstan/phpstan": "1.7.10",
 		"phpstan/phpstan-deprecation-rules": "1.0.0",
 		"phpstan/phpstan-nette": "1.0.0",
 		"phpstan/phpstan-mockery": "1.0.0",
@@ -58,7 +58,7 @@
 		]
 	},
 	"scripts": {
-		"phpstan": "phpstan analyse -c .phpstan.neon",
+		"phpstan": "phpstan analyse -c .phpstan.neon --memory-limit 1G",
 		"tests": "tester -C --colors 1 --setup ./tests/inc/setup.php ./tests/cases"
 	},
 	"config": {
diff --git a/src/Entity/Embeddable/EmbeddableContainer.php b/src/Entity/Embeddable/EmbeddableContainer.php
index f17d2704..17c9a2f9 100644
--- a/src/Entity/Embeddable/EmbeddableContainer.php
+++ b/src/Entity/Embeddable/EmbeddableContainer.php
@@ -17,6 +17,9 @@
 use function count;
 
 
+/**
+ * @implements IEntityAwareProperty<IEntity>
+ */
 class EmbeddableContainer implements IPropertyContainer, IEntityAwareProperty
 {
 	use SmartObject;
diff --git a/src/Entity/IEntityAwareProperty.php b/src/Entity/IEntityAwareProperty.php
index 379a4406..02bfb72c 100644
--- a/src/Entity/IEntityAwareProperty.php
+++ b/src/Entity/IEntityAwareProperty.php
@@ -5,17 +5,20 @@
 
 /**
  * @experimental This interface API is experimental and is subjected to change. It is ok to use its implementation.
+ * @template E of IEntity
  */
 interface IEntityAwareProperty extends IProperty
 {
 	/**
-	 * this listener is ired when property is attached to entity.
+	 * Executed when the IProperty is attached to an entity.
+	 * @phpstan-param E $entity
 	 */
 	public function onEntityAttach(IEntity $entity): void;
 
 
 	/**
-	 * This listener is fired when the entity is attached to repository.
+	 * Executed when the entity is attached to the repository.
+	 * @phpstan-param E $entity
 	 */
 	public function onEntityRepositoryAttach(IEntity $entity): void;
 }
diff --git a/src/Entity/Reflection/MetadataParser.php b/src/Entity/Reflection/MetadataParser.php
index 10b03bd9..af2943bf 100644
--- a/src/Entity/Reflection/MetadataParser.php
+++ b/src/Entity/Reflection/MetadataParser.php
@@ -525,6 +525,7 @@ protected function processRelationshipEntityProperty(PropertyMetadata $property,
 			}
 		} else {
 			$targetProperty = substr($class, $pos + 3); // skip ::$
+			assert($targetProperty !== false); // @phpstan-ignore-line
 			$class = substr($class, 0, $pos);
 
 			if (isset($args['oneSided'])) {
diff --git a/src/Relationships/HasMany.php b/src/Relationships/HasMany.php
index 68ceac8e..751efe5f 100644
--- a/src/Relationships/HasMany.php
+++ b/src/Relationships/HasMany.php
@@ -20,12 +20,19 @@
 use function spl_object_hash;
 
 
+/**
+ * @template E of IEntity
+ * @implements IRelationshipCollection<E>
+ */
 abstract class HasMany implements IRelationshipCollection
 {
 	use SmartObject;
 
 
-	/** @var IEntity */
+	/**
+	 * @var IEntity
+	 * @phpstan-var E
+	 */
 	protected $parent;
 
 	/** @var PropertyMetadata */
@@ -36,25 +43,31 @@ abstract class HasMany implements IRelationshipCollection
 
 	/**
 	 * @var ICollection|null
-	 * @phpstan-var ICollection<IEntity>|null
+	 * @phpstan-var ICollection<E>|null
 	 */
 	protected $collection;
 
-	/** @var IEntity[] */
+	/**
+	 * @var IEntity[]
+	 * @phpstan-var array<string, E>
+	 */
 	protected $toAdd = [];
 
-	/** @var IEntity[] */
+	/**
+	 * @var IEntity[]
+	 * @phpstan-var array<string,E>
+	 */
 	protected $toRemove = [];
 
-	/** @var IEntity[] */
-	protected $added = [];
-
-	/** @var IEntity[] */
+	/**
+	 * @var IEntity[]
+	 * @phpstan-var array<string, E>
+	 */
 	protected $tracked = [];
 
 	/**
 	 * @var IRepository|null
-	 * @phpstan-var IRepository<IEntity>|null
+	 * @phpstan-var IRepository<E>|null
 	 */
 	protected $targetRepository;
 
@@ -262,7 +275,7 @@ public function toCollection(): ICollection
 
 	/**
 	 * @deprecated Use toCollection() instead.
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	public function get(): ICollection
 	{
@@ -284,7 +297,7 @@ public function countStored(): int
 
 	/**
 	 * @return ICollection|IEntity[]
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	public function getIterator(): ICollection
 	{
@@ -315,7 +328,7 @@ public function trackEntity(IEntity $entity): void
 
 
 	/**
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	protected function getCollection(bool $forceNew = false): ICollection
 	{
@@ -326,16 +339,18 @@ protected function getCollection(bool $forceNew = false): ICollection
 		if ($this->parent->isPersisted()) {
 			$collection = $this->createCollection();
 		} else {
+			/** @var ICollection<E> $collection */
 			$collection = new EmptyCollection();
 		}
 
 		if (count($this->toAdd) > 0 || count($this->toRemove) > 0) {
-			/** @phpstan-var callable():array{array<string, IEntity>, array<string, IEntity>} $diffCb */
+			/** @phpstan-var callable():array{array<string, E>, array<string, E>} $diffCb */
 			$diffCb = function (): array {
 				return [$this->toAdd, $this->toRemove];
 			};
 
 			$collection = $collection->resetOrderBy();
+			/** @var ICollection<E> $collection */
 			$collection = new HasManyCollection($this->getTargetRepository(), $collection, $diffCb);
 			$collection = $this->applyDefaultOrder($collection);
 		}
@@ -349,6 +364,8 @@ protected function getCollection(bool $forceNew = false): ICollection
 
 	/**
 	 * @param IEntity|string|int $entity
+	 * @phpstan-param E|string|int $entity
+	 * @phpstan-return E|null
 	 */
 	protected function createEntity($entity, bool $need = true): ?IEntity
 	{
@@ -384,13 +401,15 @@ public function __clone()
 
 
 	/**
-	 * @phpstan-return IRepository<IEntity>
+	 * @phpstan-return IRepository<E>
 	 */
 	protected function getTargetRepository(): IRepository
 	{
 		if ($this->targetRepository === null) {
-			$this->targetRepository = $this->parent->getRepository()->getModel()
+			/** @var IRepository<E> $repository */
+			$repository = $this->parent->getRepository()->getModel()
 				->getRepository($this->metadataRelationship->repository);
+			$this->targetRepository = $repository;
 		}
 
 		return $this->targetRepository;
@@ -410,9 +429,8 @@ protected function getRelationshipMapper(): IRelationshipMapper
 
 
 	/**
-	 * @template T of ICollection<IEntity>
-	 * @phpstan-param T $collection
-	 * @phpstan-return T
+	 * @phpstan-param ICollection<E> $collection
+	 * @phpstan-return ICollection<E>
 	 */
 	protected function applyDefaultOrder(ICollection $collection): ICollection
 	{
@@ -432,19 +450,21 @@ abstract protected function modify(): void;
 
 	/**
 	 * Returns collection for has many relationship.
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	abstract protected function createCollection(): ICollection;
 
 
 	/**
 	 * Updates relationship change for the $entity.
+	 * @phpstan-param E $entity
 	 */
 	abstract protected function updateRelationshipAdd(IEntity $entity): void;
 
 
 	/**
 	 * Updates relationship change for the $entity.
+	 * @phpstan-param E $entity
 	 */
 	abstract protected function updateRelationshipRemove(IEntity $entity): void;
 }
diff --git a/src/Relationships/HasOne.php b/src/Relationships/HasOne.php
index cdb2c770..b66c82bd 100644
--- a/src/Relationships/HasOne.php
+++ b/src/Relationships/HasOne.php
@@ -15,12 +15,19 @@
 use function assert;
 
 
+/**
+ * @template E of IEntity
+ * @implements IRelationshipContainer<E>
+ */
 abstract class HasOne implements IRelationshipContainer
 {
 	use SmartObject;
 
 
-	/** @var IEntity */
+	/**
+	 * @var IEntity
+	 * @phpstan-var E
+	 */
 	protected $parent;
 
 	/** @var PropertyMetadata */
@@ -31,7 +38,7 @@ abstract class HasOne implements IRelationshipContainer
 
 	/**
 	 * @var ICollection
-	 * @phpstan-var ICollection<IEntity>
+	 * @phpstan-var ICollection<E>
 	 */
 	protected $collection;
 
@@ -41,15 +48,21 @@ abstract class HasOne implements IRelationshipContainer
 	/** @var bool Is raw value loaded from storage and not converted yet? */
 	protected $isValueFromStorage = false;
 
-	/** @var IEntity|string|int|null */
+	/**
+	 * @var IEntity|string|int|null
+	 * @phpstan-var E|string|int|null
+	 */
 	protected $value;
 
-	/** @var IEntity[] */
+	/**
+	 * @var IEntity[]
+	 * @phpstan-var list<E>
+	 */
 	protected $tracked = [];
 
 	/**
 	 * @var IRepository|null
-	 * @phpstan-var IRepository<IEntity>|null
+	 * @phpstan-var IRepository<E>|null
 	 */
 	protected $targetRepository;
 
@@ -138,6 +151,7 @@ public function isLoaded(): bool
 	 * Sets the relationship value to passed entity.
 	 * Returns true if the setter has modified property value.
 	 * @param IEntity|int|string|null $value Accepts also a primary key value.
+	 * @phpstan-param E|int|string|null $value Accepts also a primary key value.
 	 */
 	public function set($value, bool $allowNull = false): bool
 	{
@@ -212,6 +226,9 @@ protected function getPrimaryValue()
 	}
 
 
+	/**
+	 * @phpstan-return E|null
+	 */
 	protected function getValue(bool $allowPreloadContainer = true): ?IEntity
 	{
 		if (!$this->isValueValidated && $this->value !== null) {
@@ -240,6 +257,9 @@ protected function initValue(bool $allowPreloadContainer = true): void
 	}
 
 
+	/**
+	 * @phpstan-return E|null
+	 */
 	protected function fetchValue(): ?IEntity
 	{
 		$collection = $this->getCollection();
@@ -248,13 +268,15 @@ protected function fetchValue(): ?IEntity
 
 
 	/**
-	 * @phpstan-return IRepository<IEntity>
+	 * @phpstan-return IRepository<E>
 	 */
 	protected function getTargetRepository(): IRepository
 	{
 		if ($this->targetRepository === null) {
-			$this->targetRepository = $this->parent->getRepository()->getModel()
+			/** @var IRepository<E> $targetRepository */
+			$targetRepository = $this->parent->getRepository()->getModel()
 				->getRepository($this->metadataRelationship->repository);
+			$this->targetRepository = $targetRepository;
 		}
 
 		return $this->targetRepository;
@@ -262,7 +284,7 @@ protected function getTargetRepository(): IRepository
 
 
 	/**
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	protected function getCollection(): ICollection
 	{
@@ -276,6 +298,8 @@ protected function getCollection(): ICollection
 
 	/**
 	 * @param IEntity|string|int|null $entity
+	 * @phpstan-param E|string|int|null $entity
+	 * @phpstan-return E|null
 	 */
 	protected function createEntity($entity, bool $allowNull): ?IEntity
 	{
@@ -373,7 +397,7 @@ abstract protected function isImmediateEntityForPersistence(?IEntity $entity): b
 
 	/**
 	 * Creates relationship collection.
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	abstract protected function createCollection(): ICollection;
 
diff --git a/src/Relationships/IRelationshipCollection.php b/src/Relationships/IRelationshipCollection.php
index 2b3c9392..2596bf2f 100644
--- a/src/Relationships/IRelationshipCollection.php
+++ b/src/Relationships/IRelationshipCollection.php
@@ -12,13 +12,17 @@
 
 
 /**
- * @extends IteratorAggregate<int, IEntity>
+ * @template E of IEntity
+ * @extends IteratorAggregate<int, E>
+ * @extends IEntityAwareProperty<E>
  */
 interface IRelationshipCollection extends IPropertyContainer, IEntityAwareProperty, IteratorAggregate, Countable
 {
 	/**
 	 * Adds entity.
 	 * @param IEntity|string|int $entity
+	 * @phpstan-param E|string|int $entity
+	 * @phpstan-return E|null
 	 */
 	public function add($entity): ?IEntity;
 
@@ -27,6 +31,7 @@ public function add($entity): ?IEntity;
 	 * Replaces all entities with given ones.
 	 * Returns true if the setter has modified property value.
 	 * @param IEntity[]|string[]|int[] $data
+	 * @phpstan-param list<E>|list<string>|list<int> $data
 	 */
 	public function set(array $data): bool;
 
@@ -34,19 +39,22 @@ public function set(array $data): bool;
 	/**
 	 * Removes entity.
 	 * @param IEntity|string|int $entity
+	 * @phpstan-param E|string|int $entity
+	 * @phpstan-return E|null
 	 */
 	public function remove($entity): ?IEntity;
 
 
 	/**
 	 * @param IEntity|string|int $entity
+	 * @phpstan-param E|string|int $entity
 	 */
 	public function has($entity): bool;
 
 
 	/**
 	 * Returns collection of all entity.
-	 * @phpstan-return ICollection<IEntity>
+	 * @phpstan-return ICollection<E>
 	 */
 	public function toCollection(): ICollection;
 
@@ -72,6 +80,7 @@ public function countStored(): int;
 	/**
 	 * @internal
 	 * @ignore
+	 * @phpstan-param E $entity
 	 */
 	public function trackEntity(IEntity $entity): void;
 
@@ -79,7 +88,7 @@ public function trackEntity(IEntity $entity): void;
 	/**
 	 * Returns IEntity for persistence.
 	 * @return IEntity[]
-	 * @phpstan-return list<IEntity>
+	 * @phpstan-return array<string, E>
 	 * @ignore
 	 * @internal
 	 */
diff --git a/src/Relationships/IRelationshipContainer.php b/src/Relationships/IRelationshipContainer.php
index fc8ec65c..766120e2 100644
--- a/src/Relationships/IRelationshipContainer.php
+++ b/src/Relationships/IRelationshipContainer.php
@@ -8,8 +8,15 @@
 use Nextras\Orm\Entity\IPropertyContainer;
 
 
+/**
+ * @template E of IEntity
+ * @extends IEntityAwareProperty<E>
+ */
 interface IRelationshipContainer extends IPropertyContainer, IEntityAwareProperty
 {
+	/**
+	 * @phpstan-return E|null
+	 */
 	public function getEntity(): ?IEntity;
 
 
@@ -28,7 +35,7 @@ public function isModified(): bool;
 	/**
 	 * Returns IEntity for persistence.
 	 * @return IEntity[]
-	 * @phpstan-return list<IEntity>
+	 * @phpstan-return list<E>
 	 * @ignore
 	 * @internal
 	 */
@@ -38,6 +45,7 @@ public function getEntitiesForPersistence(): array;
 	/**
 	 * Returns immediate IEntity for Depth-first-search persistence.
 	 * @return IEntity|null
+	 * @phpstan-return E|null
 	 * @ignore
 	 * @internal
 	 */
diff --git a/src/Relationships/ManyHasMany.php b/src/Relationships/ManyHasMany.php
index e01f160b..1057df49 100644
--- a/src/Relationships/ManyHasMany.php
+++ b/src/Relationships/ManyHasMany.php
@@ -11,6 +11,10 @@
 use function assert;
 
 
+/**
+ * @template E of IEntity
+ * @extends HasMany<E>
+ */
 class ManyHasMany extends HasMany
 {
 	public function getEntitiesForPersistence(): array
@@ -62,7 +66,7 @@ protected function modify(): void
 
 	protected function createCollection(): ICollection
 	{
-		/** @phpstan-var callable(Traversable<mixed,IEntity>):void $subscribeCb */
+		/** @phpstan-var callable(Traversable<mixed,E>):void $subscribeCb */
 		$subscribeCb = function (Traversable $entities): void {
 			if ($this->metadataRelationship->property === null) {
 				return;
@@ -74,6 +78,7 @@ protected function createCollection(): ICollection
 		};
 		$mapper = $this->parent->getRepository()->getMapper();
 
+		/** @var ICollection<E> $collection */
 		$collection = $this->getTargetRepository()->getMapper()->createCollectionManyHasMany($mapper, $this->metadata);
 		$collection = $collection->setRelationshipParent($this->parent);
 		$collection->subscribeOnEntityFetch($subscribeCb);
diff --git a/src/Relationships/ManyHasOne.php b/src/Relationships/ManyHasOne.php
index 52a881f7..9631e0cc 100644
--- a/src/Relationships/ManyHasOne.php
+++ b/src/Relationships/ManyHasOne.php
@@ -8,10 +8,15 @@
 use function assert;
 
 
+/**
+ * @template E of IEntity
+ * @extends HasOne<E>
+ */
 class ManyHasOne extends HasOne
 {
 	protected function createCollection(): ICollection
 	{
+		/** @var ICollection<E> $collection */
 		$collection = $this->getTargetRepository()->getMapper()->createCollectionManyHasOne($this->metadata);
 		return $collection->setRelationshipParent($this->parent);
 	}
diff --git a/src/Relationships/OneHasMany.php b/src/Relationships/OneHasMany.php
index 0f0da299..38673da7 100644
--- a/src/Relationships/OneHasMany.php
+++ b/src/Relationships/OneHasMany.php
@@ -8,6 +8,10 @@
 use function assert;
 
 
+/**
+ * @template E of IEntity
+ * @extends HasMany<E>
+ */
 class OneHasMany extends HasMany
 {
 	public function getEntitiesForPersistence(): array
@@ -53,13 +57,14 @@ protected function modify(): void
 
 	protected function createCollection(): ICollection
 	{
-		/** @phpstan-var callable(\Traversable<mixed,IEntity>):void $subscribeCb */
+		/** @phpstan-var callable(\Traversable<mixed,E>):void $subscribeCb */
 		$subscribeCb = function ($entities): void {
 			foreach ($entities as $entity) {
 				$this->trackEntity($entity);
 			}
 		};
 
+		/** @var ICollection<E> $collection */
 		$collection = $this->getTargetRepository()->getMapper()->createCollectionOneHasMany($this->metadata);
 		$collection = $collection->setRelationshipParent($this->parent);
 		$collection->subscribeOnEntityFetch($subscribeCb);
diff --git a/src/Relationships/OneHasOne.php b/src/Relationships/OneHasOne.php
index c04994c1..a51eac9f 100644
--- a/src/Relationships/OneHasOne.php
+++ b/src/Relationships/OneHasOne.php
@@ -9,6 +9,10 @@
 use function assert;
 
 
+/**
+ * @template E of IEntity
+ * @extends HasOne<E>
+ */
 class OneHasOne extends HasOne
 {
 	public function __construct(PropertyMetadata $metadata)
@@ -18,9 +22,9 @@ public function __construct(PropertyMetadata $metadata)
 	}
 
 
-	/** {@inheritDoc} */
 	protected function createCollection(): ICollection
 	{
+		/** @var ICollection<E> $collection */
 		$collection = $this->getTargetRepository()->getMapper()->createCollectionOneHasOne($this->metadata);
 		return $collection->setRelationshipParent($this->parent);
 	}
diff --git a/src/Repository/IRepository.php b/src/Repository/IRepository.php
index 808a7bd2..3fe226c0 100644
--- a/src/Repository/IRepository.php
+++ b/src/Repository/IRepository.php
@@ -119,6 +119,7 @@ public function getById($id): ?IEntity;
 	 * Returns entity by primary value, throws if none found.
 	 * @param mixed $id
 	 * @throws NoResultException
+	 * @return E
 	 */
 	public function getByIdChecked($id): IEntity;
 
diff --git a/src/Repository/PersistenceHelper.php b/src/Repository/PersistenceHelper.php
index 0ce34479..a91e25a7 100644
--- a/src/Repository/PersistenceHelper.php
+++ b/src/Repository/PersistenceHelper.php
@@ -14,16 +14,16 @@
 
 class PersistenceHelper
 {
-	/** @var array<int, IRelationshipCollection|IRelationshipContainer> */
+	/** @var array<int, IRelationshipCollection<IEntity>|IRelationshipContainer<IEntity>> */
 	protected static $inputQueue = [];
 
-	/** @var array<string, IEntity|IRelationshipCollection|IRelationshipContainer|true> */
+	/** @var array<string, IEntity|IRelationshipCollection<IEntity>|IRelationshipContainer<IEntity>|true> */
 	protected static $outputQueue = [];
 
 
 	/**
 	 * @see https://en.wikipedia.org/wiki/Topological_sorting#Depth-first_search
-	 * @return array<string, IEntity|IRelationshipCollection|IRelationshipContainer|true>
+	 * @return array<string, IEntity|IRelationshipCollection<IEntity>|IRelationshipContainer<IEntity>|true>
 	 */
 	public static function getCascadeQueue(IEntity $entity, IModel $model, bool $withCascade): array
 	{
@@ -82,7 +82,7 @@ protected static function visitEntity(IEntity $entity, IModel $model, bool $with
 
 
 	/**
-	 * @param IRelationshipCollection|IRelationshipContainer $rel
+	 * @param IRelationshipCollection<IEntity>|IRelationshipContainer<IEntity> $rel
 	 */
 	protected static function visitRelationship($rel, IModel $model): void
 	{
diff --git a/src/Repository/RemovalHelper.php b/src/Repository/RemovalHelper.php
index cf0d70b1..3ff8793b 100644
--- a/src/Repository/RemovalHelper.php
+++ b/src/Repository/RemovalHelper.php
@@ -19,7 +19,7 @@
 class RemovalHelper
 {
 	/**
-	 * @param array<string, IEntity|IRelationshipCollection> $queuePersist
+	 * @param array<string, IEntity|IRelationshipCollection<IEntity>> $queuePersist
 	 * @param array<string, IEntity|bool> $queueRemove
 	 */
 	public static function getCascadeQueueAndSetNulls(
@@ -81,8 +81,8 @@ public static function getCascadeQueueAndSetNulls(
 	/**
 	 * Returns entity relationships as array, 0 => pre, 1 => post, 2 => nulls
 	 * @phpstan-return array{
-	 *      array<string, IEntity|IRelationshipCollection>,
-	 *      array<string, IEntity|IRelationshipCollection>,
+	 *      array<string, IEntity|IRelationshipCollection<IEntity>>,
+	 *      array<string, IEntity|IRelationshipCollection<IEntity>>,
 	 *      array<string, PropertyMetadata>
 	 * }
 	 */
@@ -126,7 +126,7 @@ public static function getRelationships(IEntity $entity): array
 
 	/**
 	 * @param PropertyMetadata[] $metadata
-	 * @param array<string, IEntity|IRelationshipCollection> $pre
+	 * @param array<string, IEntity|IRelationshipCollection<IEntity>> $pre
 	 * @param array<string, IEntity|bool> $queueRemove
 	 */
 	private static function setNulls(
diff --git a/src/Repository/Repository.php b/src/Repository/Repository.php
index b4f745dc..2e84b0d1 100644
--- a/src/Repository/Repository.php
+++ b/src/Repository/Repository.php
@@ -242,7 +242,6 @@ public function getById($id): ?IEntity
 	}
 
 
-	/** {@inheritdoc} */
 	public function getByIdChecked($id): IEntity
 	{
 		$entity = $this->getById($id);
@@ -253,7 +252,6 @@ public function getByIdChecked($id): IEntity
 	}
 
 
-	/** {@inheritdoc} */
 	public function findAll(): ICollection
 	{
 		return $this->mapper->findAll();
diff --git a/tests/cases/integration/Relationships/entity.relationships.phpt b/tests/cases/integration/Relationships/entity.relationships.phpt
index db9c7242..0117c1b8 100644
--- a/tests/cases/integration/Relationships/entity.relationships.phpt
+++ b/tests/cases/integration/Relationships/entity.relationships.phpt
@@ -56,7 +56,7 @@ class EntityRelationshipsTest extends DataTestCase
 
 		Assert::same(1, $book->tags->count());
 		Assert::same(1, $book->tags->countStored());
-		Assert::same('Awesome', $book->tags->toCollection()->fetch()->name);
+		Assert::same('Awesome', $book->tags->toCollection()->fetchChecked()->name);
 	}
 
 
@@ -69,7 +69,7 @@ class EntityRelationshipsTest extends DataTestCase
 		$queries = [];
 		$connection = $this->container->getByType(Connection::class);
 		$connection->addLogger(new CallbackQueryLogger(function ($query) use (& $queries): void {
-			$queries[$query] = $queries[$query] ?? 1;
+			$queries[$query] = ($queries[$query] ?? 0) + 1;
 		}));
 
 		$authors = [];
@@ -81,7 +81,7 @@ class EntityRelationshipsTest extends DataTestCase
 
 		Assert::same([1, 1, 1, 1, 2], $authors);
 		Assert::equal([], array_filter($queries, function ($count): bool {
-			return $count != 1;
+			return $count !== 1;
 		}));
 	}
 
@@ -95,7 +95,7 @@ class EntityRelationshipsTest extends DataTestCase
 		$queries = [];
 		$connection = $this->container->getByType(IConnection::class);
 		$connection->addLogger(new CallbackQueryLogger(function ($query) use (& $queries): void {
-			$queries[$query] = isset($queries[$query]) ? $queries[$query] : 1;
+			$queries[$query] = ($queries[$query] ?? 0) + 1;
 		}));
 
 		$tags = [];
@@ -112,7 +112,7 @@ class EntityRelationshipsTest extends DataTestCase
 
 		Assert::same([[1, 2, 2, 3], [3]], $tags);
 		Assert::equal([], array_filter($queries, function ($count): bool {
-			return $count != 1;
+			return $count !== 1;
 		}));
 	}
 
diff --git a/tests/cases/integration/Relationships/relationships.HasManyCollection.phpt b/tests/cases/integration/Relationships/relationships.HasManyCollection.phpt
index 464babcc..de4d982e 100644
--- a/tests/cases/integration/Relationships/relationships.HasManyCollection.phpt
+++ b/tests/cases/integration/Relationships/relationships.HasManyCollection.phpt
@@ -35,7 +35,7 @@ class RelationshipsHasManyCollectionTest extends DataTestCase
 	/** @var Author */
 	private $authorB;
 
-	/** @var OneHasMany|Book[] */
+	/** @var OneHasMany<Book> */
 	private $books;
 
 	/** @var string */
diff --git a/tests/cases/integration/Relationships/relationships.manyHasMany.collection.phpt b/tests/cases/integration/Relationships/relationships.manyHasMany.collection.phpt
index a470b760..887d5539 100644
--- a/tests/cases/integration/Relationships/relationships.manyHasMany.collection.phpt
+++ b/tests/cases/integration/Relationships/relationships.manyHasMany.collection.phpt
@@ -24,7 +24,7 @@ class RelationshipsManyHasManyCollectionTest extends DataTestCase
 	/** @var Book */
 	private $book;
 
-	/** @var ManyHasMany|Tag[] */
+	/** @var ManyHasMany<Tag> */
 	private $tags;
 
 
diff --git a/tests/cases/integration/Relationships/relationships.manyHasMany.phpt b/tests/cases/integration/Relationships/relationships.manyHasMany.phpt
index 9d4e402d..0df89161 100644
--- a/tests/cases/integration/Relationships/relationships.manyHasMany.phpt
+++ b/tests/cases/integration/Relationships/relationships.manyHasMany.phpt
@@ -32,13 +32,13 @@ class RelationshipManyHasManyTest extends DataTestCase
 		$collection = $book->tags->toCollection()->findBy(['name!=' => 'Tag 1'])->orderBy('id');
 		Assert::equal(1, $collection->count());
 		Assert::equal(1, $collection->countStored());
-		Assert::equal('Tag 2', $collection->fetch()->name);
+		Assert::equal('Tag 2', $collection->fetchChecked()->name);
 
 		$collection = $book->tags->toCollection()->findBy(['name!=' => 'Tag 3'])->orderBy('id');
 		Assert::equal(2, $collection->count());
 		Assert::equal(2, $collection->countStored());
-		Assert::equal('Tag 1', $collection->fetch()->name);
-		Assert::equal('Tag 2', $collection->fetch()->name);
+		Assert::equal('Tag 1', $collection->fetchChecked()->name);
+		Assert::equal('Tag 2', $collection->fetchChecked()->name);
 	}
 
 
@@ -142,7 +142,7 @@ class RelationshipManyHasManyTest extends DataTestCase
 		$tags = $book->tags->toCollection()->findBy(['name' => 'Tag 1']);
 		Assert::same(1, $tags->count());
 
-		$tag = $tags->fetch();
+		$tag = $tags->fetchChecked();
 		$tag->setName('XXX');
 		$this->orm->tags->persistAndFlush($tag);
 
diff --git a/tests/cases/integration/Relationships/relationships.oneHasMany.collection.phpt b/tests/cases/integration/Relationships/relationships.oneHasMany.collection.phpt
index 5f91bf6d..068fdc0c 100644
--- a/tests/cases/integration/Relationships/relationships.oneHasMany.collection.phpt
+++ b/tests/cases/integration/Relationships/relationships.oneHasMany.collection.phpt
@@ -32,7 +32,7 @@ class RelationshipsOneHasManyCollectionTest extends DataTestCase
 	/** @var Author */
 	private $authorB;
 
-	/** @var OneHasMany|Book[] */
+	/** @var OneHasMany<Book> */
 	private $books;
 
 
diff --git a/tests/inc/model/author/Author.php b/tests/inc/model/author/Author.php
index 940b7279..656a0df2 100644
--- a/tests/inc/model/author/Author.php
+++ b/tests/inc/model/author/Author.php
@@ -5,20 +5,20 @@
 
 use Nextras\Dbal\Utils\DateTimeImmutable;
 use Nextras\Orm\Entity\Entity;
-use Nextras\Orm\Relationships\OneHasMany as OHM;
+use Nextras\Orm\Relationships\OneHasMany;
 
 
 /**
- * @property int|null               $id              {primary}
- * @property string                 $name
- * @property DateTimeImmutable|null $born            {default "2021-03-21 08:23:00"}
- * @property string                 $web             {default "http://www.example.com"}
- * @property Author|null            $favoriteAuthor  {m:1 Author::$favoredBy}
- * @property OHM|Author[]           $favoredBy       {1:m Author::$favoriteAuthor}
- * @property OHM|Book[]             $books           {1:m Book::$author, orderBy=[id=DESC], cascade=[persist, remove]}
- * @property OHM|Book[]             $translatedBooks {1:m Book::$translator}
- * @property OHM|TagFollower[]      $tagFollowers    {1:m TagFollower::$author, cascade=[persist, remove]}
- * @property-read int               $age             {virtual}
+ * @property int|null                $id              {primary}
+ * @property string                  $name
+ * @property DateTimeImmutable|null  $born            {default "2021-03-21 08:23:00"}
+ * @property string                  $web             {default "http://www.example.com"}
+ * @property Author|null             $favoriteAuthor  {m:1 Author::$favoredBy}
+ * @property OneHasMany<Author>      $favoredBy       {1:m Author::$favoriteAuthor}
+ * @property OneHasMany<Book>        $books           {1:m Book::$author, orderBy=[id=DESC], cascade=[persist, remove]}
+ * @property OneHasMany<Book>        $translatedBooks {1:m Book::$translator}
+ * @property OneHasMany<TagFollower> $tagFollowers    {1:m TagFollower::$author, cascade=[persist, remove]}
+ * @property-read int                $age             {virtual}
  */
 final class Author extends Entity
 {
diff --git a/tests/inc/model/book/Book.php b/tests/inc/model/book/Book.php
index a979a77f..e078c74d 100644
--- a/tests/inc/model/book/Book.php
+++ b/tests/inc/model/book/Book.php
@@ -5,7 +5,7 @@
 
 use DateTimeImmutable;
 use Nextras\Orm\Entity\Entity;
-use Nextras\Orm\Relationships\ManyHasMany as MHM;
+use Nextras\Orm\Relationships\ManyHasMany;
 
 
 /**
@@ -13,7 +13,7 @@
  * @property string                 $title
  * @property Author                 $author       {m:1 Author::$books}
  * @property Author|null            $translator   {m:1 Author::$translatedBooks}
- * @property MHM&Tag[]              $tags         {m:m Tag::$books, isMain=true}
+ * @property ManyHasMany<Tag>       $tags         {m:m Tag::$books, isMain=true}
  * @property Book|null              $nextPart     {1:1 Book::$previousPart, isMain=true}
  * @property Book|null              $previousPart {1:1 Book::$nextPart}
  * @property Ean|null               $ean          {1:1 Ean::$book, isMain=true, cascade=[persist, remove]}
diff --git a/tests/inc/model/contents/Thread.php b/tests/inc/model/contents/Thread.php
index f4b9d0cd..9db56a08 100644
--- a/tests/inc/model/contents/Thread.php
+++ b/tests/inc/model/contents/Thread.php
@@ -7,8 +7,8 @@
 
 
 /**
- * @property-read string                $type {default thread}
- * @property      OneHasMany|Comment[]  $comments {1:m Comment::$thread, cascade=[persist, remove]}
+ * @property-read string              $type     {default thread}
+ * @property      OneHasMany<Comment> $comments {1:m Comment::$thread, cascade=[persist, remove]}
  */
 class Thread extends ThreadCommentCommon
 {
diff --git a/tests/inc/model/contents/ThreadCommentCommon.php b/tests/inc/model/contents/ThreadCommentCommon.php
index c9463e8b..47613191 100644
--- a/tests/inc/model/contents/ThreadCommentCommon.php
+++ b/tests/inc/model/contents/ThreadCommentCommon.php
@@ -7,8 +7,8 @@
 
 
 /**
- * @property      int|null              $id {primary}
- * @property-read string                $type
+ * @property      int|null $id {primary}
+ * @property-read string   $type
  */
 class ThreadCommentCommon extends Entity
 {
diff --git a/tests/inc/model/log/Log.php b/tests/inc/model/log/Log.php
index fa65d65a..035bbd2a 100644
--- a/tests/inc/model/log/Log.php
+++ b/tests/inc/model/log/Log.php
@@ -10,7 +10,7 @@
 /**
  * @property DateTimeImmutable $id     {primary-proxy}
  * @property DateTimeImmutable $date   {primary}
- * @property int $count
+ * @property int               $count
  */
 final class Log extends Entity
 {
diff --git a/tests/inc/model/photoAlbum/PhotoAlbum.php b/tests/inc/model/photoAlbum/PhotoAlbum.php
index 10ffd68f..373228cf 100644
--- a/tests/inc/model/photoAlbum/PhotoAlbum.php
+++ b/tests/inc/model/photoAlbum/PhotoAlbum.php
@@ -4,14 +4,14 @@
 
 
 use Nextras\Orm\Entity\Entity;
-use Nextras\Orm\Relationships\OneHasMany as OHM;
+use Nextras\Orm\Relationships\OneHasMany;
 
 
 /**
- * @property int|null    $id      {primary}
- * @property string      $title
- * @property Photo[]|OHM $photos  {1:m Photo::$album}
- * @property Photo|null  $preview {1:1 Photo::$previewFor, isMain=true}
+ * @property int|null          $id      {primary}
+ * @property string            $title
+ * @property OneHasMany<Photo> $photos  {1:m Photo::$album}
+ * @property Photo|null        $preview {1:1 Photo::$previewFor, isMain=true}
  */
 final class PhotoAlbum extends Entity
 {
diff --git a/tests/inc/model/publisher/Publisher.php b/tests/inc/model/publisher/Publisher.php
index 223e96c3..661a2cc5 100644
--- a/tests/inc/model/publisher/Publisher.php
+++ b/tests/inc/model/publisher/Publisher.php
@@ -4,16 +4,16 @@
 
 
 use Nextras\Orm\Entity\Entity;
-use Nextras\Orm\Relationships\ManyHasMany as MHM;
-use Nextras\Orm\Relationships\OneHasMany as OHM;
+use Nextras\Orm\Relationships\ManyHasMany;
+use Nextras\Orm\Relationships\OneHasMany;
 
 
 /**
- * @property int|null   $id          {primary-proxy}
- * @property int|null   $publisherId {primary}
- * @property string     $name
- * @property OHM|Book[] $books       {1:m Book::$publisher}
- * @property MHM|Tag[]  $tags        {m:m Tag::$publishers, isMain=true}
+ * @property int|null         $id          {primary-proxy}
+ * @property int|null         $publisherId {primary}
+ * @property string           $name
+ * @property OneHasMany<Book> $books       {1:m Book::$publisher}
+ * @property ManyHasMany<Tag> $tags        {m:m Tag::$publishers, isMain=true}
  */
 final class Publisher extends Entity
 {
diff --git a/tests/inc/model/tag/Tag.php b/tests/inc/model/tag/Tag.php
index 456db620..5f8bcce0 100644
--- a/tests/inc/model/tag/Tag.php
+++ b/tests/inc/model/tag/Tag.php
@@ -9,12 +9,12 @@
 
 
 /**
- * @property-read int|null $id                            {primary}
- * @property-read string $name
- * @property-read ICollection|Book[] $books               {m:m Book::$tags, exposeCollection=true}
- * @property-read ICollection|Publisher[] $publishers     {m:m Publisher::$tags, exposeCollection=true}
- * @property-read ICollection|TagFollower[] $tagFollowers {1:m TagFollower::$tag, cascade=[persist, remove], exposeCollection=true}
- * @property-read bool $isGlobal                          {default true}
+ * @property-read int|null                 $id           {primary}
+ * @property-read string                   $name
+ * @property-read ICollection<Book>        $books        {m:m Book::$tags, exposeCollection=true}
+ * @property-read ICollection<Publisher>   $publishers   {m:m Publisher::$tags, exposeCollection=true}
+ * @property-read ICollection<TagFollower> $tagFollowers {1:m TagFollower::$tag, cascade=[persist, remove], exposeCollection=true}
+ * @property-read bool                     $isGlobal     {default true}
  */
 final class Tag extends Entity
 {
@@ -37,6 +37,6 @@ public function setBooks(Book ...$books): void
 	{
 		$relationship = $this->getProperty('books');
 		assert($relationship instanceof HasMany);
-		$relationship->set($books);
+		$relationship->set(array_values($books));
 	}
 }
diff --git a/tests/inc/model/tagFollower/TagFollower.php b/tests/inc/model/tagFollower/TagFollower.php
index 32447965..39f28892 100644
--- a/tests/inc/model/tagFollower/TagFollower.php
+++ b/tests/inc/model/tagFollower/TagFollower.php
@@ -7,9 +7,9 @@
 
 
 /**
- * @property array             $id        {primary-proxy}
- * @property Author            $author    {m:1 Author::$tagFollowers} {primary}
- * @property Tag               $tag       {m:1 Tag::$tagFollowers} {primary}
+ * @property array  $id        {primary-proxy}
+ * @property Author $author    {m:1 Author::$tagFollowers} {primary}
+ * @property Tag    $tag       {m:1 Tag::$tagFollowers} {primary}
  */
 final class TagFollower extends Entity
 {
diff --git a/tests/inc/model/user/User.php b/tests/inc/model/user/User.php
index 9e01ce9c..2b9bd473 100644
--- a/tests/inc/model/user/User.php
+++ b/tests/inc/model/user/User.php
@@ -4,13 +4,13 @@
 
 
 use Nextras\Orm\Entity\Entity;
-use Nextras\Orm\Relationships\ManyHasMany as MHM;
+use Nextras\Orm\Relationships\ManyHasMany;
 
 
 /**
- * @property int|null   $id            {primary}
- * @property MHM|User[] $myFriends     {m:m User::$friendsWithMe, isMain=true}
- * @property MHM|User[] $friendsWithMe {m:m User::$myFriends}
+ * @property int|null          $id            {primary}
+ * @property ManyHasMany<User> $myFriends     {m:m User::$friendsWithMe, isMain=true}
+ * @property ManyHasMany<User> $friendsWithMe {m:m User::$myFriends}
  */
 final class User extends Entity
 {