Merge pull request #517 from gam6itko/load-eager-test

Add `unset` behavior

Author: roxblnfk

psalm-baseline.xml

@@ -13,6 +13,8 @@
         </ignoreFiles>
     </projectFiles>
     <issueHandlers>
+        <MissingOverrideAttribute errorLevel="suppress" />
+        <PossiblyUnusedMethod errorLevel="suppress" />
         <MissingClassConstType errorLevel="suppress" />
         <UnusedClass errorLevel="suppress" />
         <UndefinedAttributeClass>

psalm.xml

@@ -7,6 +7,7 @@
 use Cycle\Database\Injection\ValueInterface;
 use Cycle\ORM\Heap\Traits\RelationTrait;
 use Cycle\ORM\Reference\ReferenceInterface;
+use Cycle\ORM\Relation\SpecialValue;
 use Cycle\ORM\RelationMap;
 use JetBrains\PhpStorm\ExpectedValues;
 
@@ -191,6 +192,10 @@ public function syncState(RelationMap $relMap, State $state): array
         $changes = \array_udiff_assoc($state->getTransactionData(), $this->data, [self::class, 'compare']);
 
         foreach ($state->getRelations() as $name => $value) {
+            if (SpecialValue::isNotSet($value)) {
+                continue;
+            }
+
             if ($value instanceof ReferenceInterface) {
                 $changes[$name] = $value->hasValue() ? $value->getValue() : $value;
             }

src/Heap/Node.php

@@ -46,16 +46,19 @@ final class ORM implements ORMInterface
     private RepositoryProvider $repositoryProvider;
     private EntityProvider $entityProvider;
     private RoleResolverInterface $roleResolver;
+    private Options $options;
 
     public function __construct(
         private FactoryInterface $factory,
         private SchemaInterface $schema,
         ?CommandGeneratorInterface $commandGenerator = null,
         ?HeapInterface $heap = null,
+        ?Options $options = null,
     ) {
         $this->heap = $heap ?? new Heap();
         $this->commandGenerator = $commandGenerator ?? new CommandGenerator();
         $this->resetRegistry();
+        $this->options = $options ?? new Options();
     }
 
     public function resolveRole(string|object $entity): string
@@ -93,6 +96,7 @@ public function getService(
             RepositoryProviderInterface::class,
             SourceProviderInterface::class,
             TypecastProviderInterface::class,
+            Options::class,
         ])]
         string $class,
     ): object {
@@ -105,6 +109,7 @@ public function getService(
             MapperProviderInterface::class => $this->mapperProvider,
             RelationProviderInterface::class => $this->relationProvider,
             RepositoryProviderInterface::class => $this->repositoryProvider,
+            Options::class => $this->options,
             default => throw new \InvalidArgumentException("Undefined service `$class`."),
         };
     }
@@ -161,6 +166,7 @@ public function with(
         ?SchemaInterface $schema = null,
         ?FactoryInterface $factory = null,
         ?HeapInterface $heap = null,
+        ?Options $options = null,
     ): ORMInterface {
         $heap ??= clone $this->heap;
         $heap->clean();
@@ -170,6 +176,7 @@ public function with(
             schema: $schema ?? $this->schema,
             commandGenerator: $this->commandGenerator,
             heap: $heap,
+            options: $options,
         );
     }
 

src/ORM.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM;
+
+/**
+ * ORM behavior options.
+ */
+final class Options
+{
+    /**
+     * @readonly
+     */
+    public bool $ignoreUninitializedRelations = true;
+
+    /**
+     * If TRUE, ORM will ignore relations on uninitialized Entity properties.
+     * In this case, `unset($entity->relation)` will not change the relation when saving,
+     * and it will hydrate it if the relation is loaded in the query.
+     *
+     * If FALSE, uninitialized properties will be treated as NULL (an empty collection or empty value).
+     * `unset($entity->relation)` will lead to a change in the relation
+     * (removing the link with another entity or entities).
+     */
+    public function withIgnoreUninitializedRelations(bool $value): static
+    {
+        $clone = clone $this;
+        $clone->ignoreUninitializedRelations = $value;
+        return $clone;
+    }
+}

src/Options.php

@@ -36,8 +36,17 @@ public function __construct(ORMInterface $orm, string $role, string $name, strin
     public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = true): void
     {
         $state = $tuple->state;
-
         $relName = $this->getName();
+
+        if (SpecialValue::isNotSet($related)) {
+            if (!$state->hasRelation($relName)) {
+                $state->setRelationStatus($relName, RelationInterface::STATUS_DEFERRED);
+                return;
+            }
+
+            $related = $state->getRelation($relName);
+        }
+
         if ($state->hasRelation($relName)) {
             $prefill = $state->getRelation($relName);
             $nodeValue = $tuple->node->getRelation($relName);
@@ -70,11 +79,18 @@ public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = t
     public function queue(Pool $pool, Tuple $tuple): void
     {
         $state = $tuple->state;
-        $related = $state->getRelation($this->getName());
+        $relName = $this->getName();
+
+        if (!$state->hasRelation($relName)) {
+            $state->setRelationStatus($relName, RelationInterface::STATUS_RESOLVED);
+            return;
+        }
+
+        $related = $state->getRelation($relName);
 
         if ($related instanceof ReferenceInterface && $related->hasValue()) {
             $related = $related->getValue();
-            $state->setRelation($this->getName(), $related);
+            $state->setRelation($relName, $related);
         }
         if ($related === null) {
             $this->setNullFromRelated($tuple, false);
@@ -86,11 +102,11 @@ public function queue(Pool $pool, Tuple $tuple): void
                 foreach ($this->outerKeys as $i => $outerKey) {
                     $state->register($this->innerKeys[$i], $scope[$outerKey]);
                 }
-                $state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+                $state->setRelationStatus($relName, RelationInterface::STATUS_RESOLVED);
                 return;
             }
             if ($tuple->status >= Tuple::STATUS_WAITED) {
-                $state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+                $state->setRelationStatus($relName, RelationInterface::STATUS_RESOLVED);
             }
             return;
         }
@@ -99,8 +115,8 @@ public function queue(Pool $pool, Tuple $tuple): void
 
         if ($this->shouldPull($tuple, $rTuple)) {
             $this->pullValues($state, $rTuple->state);
-            $state->setRelation($this->getName(), $related);
-            $state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+            $state->setRelation($relName, $related);
+            $state->setRelationStatus($relName, RelationInterface::STATUS_RESOLVED);
         }
     }
 

src/Relation/BelongsTo.php

@@ -120,6 +120,12 @@ public function queue(Pool $pool, Tuple $tuple, ?StoreCommandInterface $command
         if ($tuple->task !== Tuple::TASK_STORE) {
             return;
         }
+
+        if (!$tuple->state->hasRelation($this->getName())) {
+            $tuple->state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+            return;
+        }
+
         $related = $tuple->state->getRelation($this->getName());
 
         // Master Node

src/Relation/Embedded.php

@@ -56,13 +56,17 @@ public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = t
                 $tuple->state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
                 return;
             }
+
             $original = $this->resolve($original, true);
             $node->setRelation($this->getName(), $original);
         }
 
         if ($related instanceof ReferenceInterface) {
             $related = $this->resolve($related, true);
             $tuple->state->setRelation($this->getName(), $related);
+        } elseif (SpecialValue::isNotSet($related)) {
+            $tuple->state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+            return;
         } elseif (!\is_iterable($related)) {
             if ($related === null) {
                 $related = $this->collect([]);
@@ -73,8 +77,10 @@ public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = t
                 ));
             }
         }
-        foreach ($this->calcDeleted($related, $original ?? []) as $item) {
-            $this->deleteChild($pool, $tuple, $item);
+        if (!SpecialValue::isEmpty($original)) {
+            foreach ($this->calcDeleted($related, $original) as $item) {
+                $this->deleteChild($pool, $tuple, $item);
+            }
         }
 
         if (\count($related) === 0) {

src/Relation/HasMany.php

@@ -53,6 +53,9 @@ public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = t
         if ($related instanceof ReferenceInterface) {
             $related = $this->resolve($related, true);
             $tuple->state->setRelation($this->getName(), $related);
+        } elseif (SpecialValue::isNotSet($related)) {
+            $tuple->state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+            return;
         }
 
         if ($related === null) {

src/Relation/HasOne.php

@@ -84,7 +84,11 @@ public function prepare(Pool $pool, Tuple $tuple, mixed $related, bool $load = t
         if ($related instanceof ReferenceInterface && $this->resolve($related, true) !== null) {
             $related = $related->getValue();
             $tuple->state->setRelation($this->getName(), $related);
+        } elseif (SpecialValue::isNotSet($related)) {
+            $tuple->state->setRelationStatus($this->getName(), RelationInterface::STATUS_RESOLVED);
+            return;
         }
+
         $related = $this->extractRelated($related, $original);
         // $tuple->state->setStorage($this->pivotEntity, $related);
         $tuple->state->setRelation($this->getName(), $related);