relationships: make HasOne relationship lazy until entity is attached

doc/entity.texy

@@ -42,7 +42,7 @@ echo $member->hasValue('web') ? 'has web' : '-';
 $member->isPersisted(); // false
 \--
 
-Attaching entities to the repository is letting Orm know about your entities, it does not store the entity. Attaching to repository injects the required dependencies into your entity (through inject property annotations or inject methods). If you need some dependency before attaching entity to the repository, feel free to pass the dependency through the constructor, which is by default empty.
+Attaching entities to the repository lets Orm know about your entities. Attaching to a repository runs the required dependencies injection into your entity (through inject property annotations or inject methods). If you need some dependency before attaching entity to the repository, feel free to pass the dependency via the constructor, which is by default empty.
 
 Each entity can be created "manually". Entities can be simply connected together. Let's see an example:
 
@@ -54,7 +54,7 @@ $book->author = $author;
 $book->tags->set([new Tag(), new Tag()]);
 \--
 
-If a instance Author is attached to the repository, all other new connected entities are automatically attached to their repositories too. See more in [relationships chapter | relationships].
+If an Author instance is attached to the repository, all other new connected entities are automatically attached to their repositories too. See more in [relationships chapter | relationships].
 
 -----------
 

src/Entity/AbstractEntity.php

@@ -221,6 +221,7 @@ public function __clone()
 	{
 		$id = $this->hasValue('id') ? $this->getValue('id') : null;
 		$persistedId = $this->persistedId;
+		$isAttached = $this->isAttached();
 		foreach ($this->getMetadata()->getProperties() as $name => $metadataProperty) {
 			// getValue loads data & checks for not null values
 			if ($this->hasValue($name) && is_object($this->data[$name])) {
@@ -229,18 +230,27 @@ public function __clone()
 					$this->data['id'] = null;
 					$this->persistedId = null;
 					$this->data[$name] = clone $this->data[$name];
-					$this->data[$name]->setPropertyEntity($this);
+					$this->data[$name]->onEntityAttach($this);
+					if ($isAttached) {
+						$this->data[$name]->onEntityRepositoryAttach($this);
+					}
 					$this->data[$name]->set($data);
 					$this->data['id'] = $id;
 					$this->persistedId = $persistedId;
 
 				} elseif ($this->data[$name] instanceof IRelationshipContainer) {
 					$this->data[$name] = clone $this->data[$name];
-					$this->data[$name]->setPropertyEntity($this);
+					$this->data[$name]->onEntityAttach($this);
+					if ($isAttached) {
+						$this->data[$name]->onEntityRepositoryAttach($this);
+					}
 
 				} elseif ($this->data[$name] instanceof EmbeddableContainer) {
 					$this->data[$name] = clone $this->data[$name];
-					$this->data[$name]->setPropertyEntity($this);
+					$this->data[$name]->onEntityAttach($this);
+					if ($isAttached) {
+						$this->data[$name]->onEntityRepositoryAttach($this);
+					}
 
 				} else {
 					$this->data[$name] = clone $this->data[$name];
@@ -309,8 +319,18 @@ public function onFree(): void
 
 	public function onAttach(IRepository $repository, EntityMetadata $metadata): void
 	{
-		$this->attach($repository);
+		if ($this->isAttached()) {
+			return;
+		}
+
+		$this->repository = $repository;
 		$this->metadata = $metadata;
+
+		foreach ($this->data as $property) {
+			if ($property instanceof IEntityAwareProperty) {
+				$property->onEntityRepositoryAttach($this);
+			}
+		}
 	}
 
 
@@ -499,22 +519,12 @@ private function createPropertyWrapper(PropertyMetadata $metadata): IProperty
 		assert($wrapper instanceof IProperty);
 
 		if ($wrapper instanceof IEntityAwareProperty) {
-			$wrapper->setPropertyEntity($this);
+			$wrapper->onEntityAttach($this);
+			if ($this->isAttached()) {
+				$wrapper->onEntityRepositoryAttach($this);
+			}
 		}
 
 		return $wrapper;
 	}
-
-
-	/**
-	 * @param IRepository<IEntity> $repository
-	 */
-	private function attach(IRepository $repository): void
-	{
-		if ($this->repository !== null && $this->repository !== $repository) {
-			throw new InvalidStateException('Entity is already attached.');
-		}
-
-		$this->repository = $repository;
-	}
 }

src/Entity/Embeddable/Embeddable.php

@@ -79,6 +79,8 @@ public function onAttach(IEntity $entity): void
 	}
 
 
+
+
 	/**
 	 * @return mixed
 	 */
@@ -144,7 +146,7 @@ private function createPropertyWrapper(PropertyMetadata $metadata): IProperty
 			if ($this->parentEntity === null) {
 				throw new InvalidStateException("");
 			} else {
-				$wrapper->setPropertyEntity($this->parentEntity);
+				$wrapper->onEntityAttach($this->parentEntity);
 			}
 		}
 

src/Entity/Embeddable/EmbeddableContainer.php

@@ -50,12 +50,17 @@ public function __construct(PropertyMetadata $propertyMetadata)
 	}
 
 
-	public function setPropertyEntity(IEntity $entity): void
+	public function onEntityAttach(IEntity $entity): void
 	{
 		$this->entity = $entity;
 	}
 
 
+	public function onEntityRepositoryAttach(IEntity $entity): void
+	{
+	}
+
+
 	public function convertToRawValue($value)
 	{
 		return $value;

src/Entity/Embeddable/IEmbeddable.php

@@ -6,6 +6,9 @@
 use Nextras\Orm\Entity\IEntity;
 
 
+/**
+ * @experimental This interface API is experimental and is subjected to change. It is ok to use its implementation.
+ */
 interface IEmbeddable
 {
 	/**

src/Entity/IEntityAwareProperty.php

@@ -3,7 +3,19 @@
 namespace Nextras\Orm\Entity;
 
 
+/**
+ * @experimental This interface API is experimental and is subjected to change. It is ok to use its implementation.
+ */
 interface IEntityAwareProperty extends IProperty
 {
-	public function setPropertyEntity(IEntity $entity): void;
+	/**
+	 * this listener is ired when property is attached to entity.
+	 */
+	public function onEntityAttach(IEntity $entity): void;
+
+
+	/**
+	 * This listener is fired when the entity is attached to repository.
+	 */
+	public function onEntityRepositoryAttach(IEntity $entity): void;
 }

src/Relationships/HasMany.php

@@ -81,13 +81,14 @@ public function __construct(PropertyMetadata $metadata)
 	}
 
 
-	/**
-	 * @internal
-	 * @ignore
-	 */
-	public function setPropertyEntity(IEntity $parent): void
+	public function onEntityAttach(IEntity $entity): void
+	{
+		$this->parent = $entity;
+	}
+
+
+	public function onEntityRepositoryAttach(IEntity $entity): void
 	{
-		$this->parent = $parent;
 	}