1. <?php
3. declare(strict_types=1);
5. namespace Doctrine\ODM\MongoDB;
7. use Doctrine\Common\Collections\ArrayCollection;
8. use Doctrine\Common\Collections\Collection;
9. use Doctrine\Common\EventManager;
10. use Doctrine\ODM\MongoDB\Hydrator\HydratorFactory;
11. use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
12. use Doctrine\ODM\MongoDB\Mapping\MappingException;
13. use Doctrine\ODM\MongoDB\PersistentCollection\PersistentCollectionException;
14. use Doctrine\ODM\MongoDB\PersistentCollection\PersistentCollectionInterface;
15. use Doctrine\ODM\MongoDB\Persisters\CollectionPersister;
16. use Doctrine\ODM\MongoDB\Persisters\PersistenceBuilder;
17. use Doctrine\ODM\MongoDB\Query\Query;
18. use Doctrine\ODM\MongoDB\Types\DateType;
19. use Doctrine\ODM\MongoDB\Types\Type;
20. use Doctrine\ODM\MongoDB\Utility\CollectionHelper;
21. use Doctrine\ODM\MongoDB\Utility\LifecycleEventManager;
22. use Doctrine\Persistence\Mapping\ReflectionService;
23. use Doctrine\Persistence\Mapping\RuntimeReflectionService;
24. use Doctrine\Persistence\NotifyPropertyChanged;
25. use Doctrine\Persistence\PropertyChangedListener;
26. use InvalidArgumentException;
27. use MongoDB\BSON\UTCDateTime;
28. use MongoDB\Driver\WriteConcern;
29. use ProxyManager\Proxy\GhostObjectInterface;
30. use ReflectionProperty;
31. use UnexpectedValueException;
33. use function array_filter;
34. use function assert;
35. use function count;
36. use function get_class;
37. use function in_array;
38. use function is_array;
39. use function is_object;
40. use function method_exists;
41. use function preg_match;
42. use function serialize;
43. use function spl_object_hash;
44. use function sprintf;
46. /**
47.  * The UnitOfWork is responsible for tracking changes to objects during an
48.  * "object-level" transaction and for writing out changes to the database
49.  * in the correct order.
50.  *
51.  * @psalm-import-type FieldMapping from ClassMetadata
52.  * @psalm-import-type AssociationFieldMapping from ClassMetadata
53.  * @psalm-type ChangeSet = array{
54.  *      0: mixed,
55.  *      1: mixed
56.  * }
57.  * @psalm-type Hints = array<int, mixed>
58.  * @psalm-type CommitOptions array{
59.  *      fsync?: bool,
60.  *      safe?: int,
61.  *      w?: int,
62.  *      writeConcern?: WriteConcern
63.  * }
64.  */
65. final class UnitOfWork implements PropertyChangedListener
66. {
67.     /**
68.      * A document is in MANAGED state when its persistence is managed by a DocumentManager.
69.      */
70.     public const STATE_MANAGED = 1;
72.     /**
73.      * A document is new if it has just been instantiated (i.e. using the "new" operator)
74.      * and is not (yet) managed by a DocumentManager.
75.      */
76.     public const STATE_NEW = 2;
78.     /**
79.      * A detached document is an instance with a persistent identity that is not
80.      * (or no longer) associated with a DocumentManager (and a UnitOfWork).
81.      */
82.     public const STATE_DETACHED = 3;
84.     /**
85.      * A removed document instance is an instance with a persistent identity,
86.      * associated with a DocumentManager, whose persistent state has been
87.      * deleted (or is scheduled for deletion).
88.      */
89.     public const STATE_REMOVED = 4;
91.     /**
92.      * The identity map holds references to all managed documents.
93.      *
94.      * Documents are grouped by their class name, and then indexed by the
95.      * serialized string of their database identifier field or, if the class
96.      * has no identifier, the SPL object hash. Serializing the identifier allows
97.      * differentiation of values that may be equal (via type juggling) but not
98.      * identical.
99.      *
100.      * Since all classes in a hierarchy must share the same identifier set,
101.      * we always take the root class name of the hierarchy.
102.      *
103.      * @psalm-var array<class-string, array<string, object>>
104.      */
105.     private array $identityMap = [];
107.     /**
108.      * Map of all identifiers of managed documents.
109.      * Keys are object ids (spl_object_hash).
110.      *
111.      * @var array<string, mixed>
112.      */
113.     private array $documentIdentifiers = [];
115.     /**
116.      * Map of the original document data of managed documents.
117.      * Keys are object ids (spl_object_hash). This is used for calculating changesets
118.      * at commit time.
119.      *
120.      * @internal Note that PHPs "copy-on-write" behavior helps a lot with memory usage.
121.      *           A value will only really be copied if the value in the document is modified
122.      *           by the user.
123.      *
124.      * @var array<string, array<string, mixed>>
125.      */
126.     private array $originalDocumentData = [];
128.     /**
129.      * Map of document changes. Keys are object ids (spl_object_hash).
130.      * Filled at the beginning of a commit of the UnitOfWork and cleaned at the end.
131.      *
132.      * @psalm-var array<string, array<string, ChangeSet>>
133.      */
134.     private array $documentChangeSets = [];
136.     /**
137.      * The (cached) states of any known documents.
138.      * Keys are object ids (spl_object_hash).
139.      *
140.      * @psalm-var array<string, self::STATE_*>
141.      */
142.     private array $documentStates = [];
144.     /**
145.      * Map of documents that are scheduled for dirty checking at commit time.
146.      *
147.      * Documents are grouped by their class name, and then indexed by their SPL
148.      * object hash. This is only used for documents with a change tracking
149.      * policy of DEFERRED_EXPLICIT.
150.      *
151.      * @psalm-var array<class-string, array<string, object>>
152.      */
153.     private array $scheduledForSynchronization = [];
155.     /**
156.      * A list of all pending document insertions.
157.      *
158.      * @var array<string, object>
159.      */
160.     private array $documentInsertions = [];
162.     /**
163.      * A list of all pending document updates.
164.      *
165.      * @var array<string, object>
166.      */
167.     private array $documentUpdates = [];
169.     /**
170.      * A list of all pending document upserts.
171.      *
172.      * @var array<string, object>
173.      */
174.     private array $documentUpserts = [];
176.     /**
177.      * A list of all pending document deletions.
178.      *
179.      * @var array<string, object>
180.      */
181.     private array $documentDeletions = [];
183.     /**
184.      * All pending collection deletions.
185.      *
186.      * @psalm-var array<string, PersistentCollectionInterface<array-key, object>>
187.      */
188.     private array $collectionDeletions = [];
190.     /**
191.      * All pending collection updates.
192.      *
193.      * @psalm-var array<string, PersistentCollectionInterface<array-key, object>>
194.      */
195.     private array $collectionUpdates = [];
197.     /**
198.      * A list of documents related to collections scheduled for update or deletion
199.      *
200.      * @psalm-var array<string, array<string, PersistentCollectionInterface<array-key, object>>>
201.      */
202.     private array $hasScheduledCollections = [];
204.     /**
205.      * List of collections visited during changeset calculation on a commit-phase of a UnitOfWork.
206.      * At the end of the UnitOfWork all these collections will make new snapshots
207.      * of their data.
208.      *
209.      * @psalm-var array<string, array<PersistentCollectionInterface<array-key, object>>>
210.      */
211.     private array $visitedCollections = [];
213.     /**
214.      * The DocumentManager that "owns" this UnitOfWork instance.
215.      */
216.     private DocumentManager $dm;
218.     /**
219.      * The EventManager used for dispatching events.
220.      */
221.     private EventManager $evm;
223.     /**
224.      * Additional documents that are scheduled for removal.
225.      *
226.      * @var array<string, object>
227.      */
228.     private array $orphanRemovals = [];
230.     /**
231.      * The HydratorFactory used for hydrating array Mongo documents to Doctrine object documents.
232.      */
233.     private HydratorFactory $hydratorFactory;
235.     /**
236.      * The document persister instances used to persist document instances.
237.      *
238.      * @psalm-var array<class-string, Persisters\DocumentPersister>
239.      */
240.     private array $persisters = [];
242.     /**
243.      * The collection persister instance used to persist changes to collections.
244.      */
245.     private ?CollectionPersister $collectionPersister = null;
247.     /**
248.      * The persistence builder instance used in DocumentPersisters.
249.      */
250.     private ?PersistenceBuilder $persistenceBuilder = null;
252.     /**
253.      * Array of parent associations between embedded documents.
254.      *
255.      * @psalm-var array<string, array{0: AssociationFieldMapping, 1: object|null, 2: string}>
256.      */
257.     private array $parentAssociations = [];
259.     private LifecycleEventManager $lifecycleEventManager;
261.     private ReflectionService $reflectionService;
263.     /**
264.      * Array of embedded documents known to UnitOfWork. We need to hold them to prevent spl_object_hash
265.      * collisions in case already managed object is lost due to GC (so now it won't). Embedded documents
266.      * found during doDetach are removed from the registry, to empty it altogether clear() can be utilized.
267.      *
268.      * @var array<string, object>
269.      */
270.     private array $embeddedDocumentsRegistry = [];
272.     private int $commitsInProgress = 0;
274.     /**
275.      * Initializes a new UnitOfWork instance, bound to the given DocumentManager.
276.      */
277.     public function __construct(DocumentManager $dm, EventManager $evm, HydratorFactory $hydratorFactory)
278.     {
279.         $this->dm                    = $dm;
280.         $this->evm                   = $evm;
281.         $this->hydratorFactory       = $hydratorFactory;
282.         $this->lifecycleEventManager = new LifecycleEventManager($dm, $this, $evm);
283.         $this->reflectionService     = new RuntimeReflectionService();
284.     }
286.     /**
287.      * Factory for returning new PersistenceBuilder instances used for preparing data into
288.      * queries for insert persistence.
289.      *
290.      * @internal
291.      */
292.     public function getPersistenceBuilder(): PersistenceBuilder
293.     {
294.         if (! $this->persistenceBuilder) {
295.             $this->persistenceBuilder = new PersistenceBuilder($this->dm, $this);
296.         }
298.         return $this->persistenceBuilder;
299.     }
301.     /**
302.      * Sets the parent association for a given embedded document.
303.      *
304.      * @internal
305.      *
306.      * @psalm-param FieldMapping $mapping
307.      */
308.     public function setParentAssociation(object $document, array $mapping, ?object $parent, string $propertyPath): void
309.     {
310.         $oid                                   = spl_object_hash($document);
311.         $this->embeddedDocumentsRegistry[$oid] = $document;
312.         $this->parentAssociations[$oid]        = [$mapping, $parent, $propertyPath];
313.     }
315.     /**
316.      * Gets the parent association for a given embedded document.
317.      *
318.      *     <code>
319.      *     list($mapping, $parent, $propertyPath) = $this->getParentAssociation($embeddedDocument);
320.      *     </code>
321.      *
322.      * @psalm-return array{0: AssociationFieldMapping, 1: object|null, 2: string}|null
323.      */
324.     public function getParentAssociation(object $document): ?array
325.     {
326.         $oid = spl_object_hash($document);
328.         return $this->parentAssociations[$oid] ?? null;
329.     }
331.     /**
332.      * Get the document persister instance for the given document name
333.      *
334.      * @psalm-param class-string<T> $documentName
335.      *
336.      * @psalm-return Persisters\DocumentPersister<T>
337.      *
338.      * @template T of object
339.      */
340.     public function getDocumentPersister(string $documentName): Persisters\DocumentPersister
341.     {
342.         if (! isset($this->persisters[$documentName])) {
343.             $class                           = $this->dm->getClassMetadata($documentName);
344.             $pb                              = $this->getPersistenceBuilder();
345.             $this->persisters[$documentName] = new Persisters\DocumentPersister($pb, $this->dm, $this, $this->hydratorFactory, $class);
346.         }
348.         /** @psalm-var Persisters\DocumentPersister<T> */
349.         return $this->persisters[$documentName];
350.     }
352.     /**
353.      * Get the collection persister instance.
354.      */
355.     public function getCollectionPersister(): CollectionPersister
356.     {
357.         if (! isset($this->collectionPersister)) {
358.             $pb                        = $this->getPersistenceBuilder();
359.             $this->collectionPersister = new Persisters\CollectionPersister($this->dm, $pb, $this);
360.         }
362.         return $this->collectionPersister;
363.     }
365.     /**
366.      * Set the document persister instance to use for the given document name
367.      *
368.      * @internal
369.      *
370.      * @psalm-param class-string<T> $documentName
371.      * @psalm-param Persisters\DocumentPersister<T> $persister
372.      *
373.      * @template T of object
374.      */
375.     public function setDocumentPersister(string $documentName, Persisters\DocumentPersister $persister): void
376.     {
377.         $this->persisters[$documentName] = $persister;
378.     }
380.     /**
381.      * Commits the UnitOfWork, executing all operations that have been postponed
382.      * up to this point. The state of all managed documents will be synchronized with
383.      * the database.
384.      *
385.      * The operations are executed in the following order:
386.      *
387.      * 1) All document insertions
388.      * 2) All document updates
389.      * 3) All document deletions
390.      *
391.      * @param array $options Array of options to be used with batchInsert(), update() and remove()
392.      * @psalm-param CommitOptions $options
393.      */
394.     public function commit(array $options = []): void
395.     {
396.         // Raise preFlush
397.         $this->evm->dispatchEvent(Events::preFlush, new Event\PreFlushEventArgs($this->dm));
399.         // Compute changes done since last commit.
400.         $this->computeChangeSets();
402.         if (
403.             ! ($this->documentInsertions ||
404.             $this->documentUpserts ||
405.             $this->documentDeletions ||
406.             $this->documentUpdates ||
407.             $this->collectionUpdates ||
408.             $this->collectionDeletions ||
409.             $this->orphanRemovals)
410.         ) {
411.             return; // Nothing to do.
412.         }
414.         $this->commitsInProgress++;
415.         if ($this->commitsInProgress > 1) {
416.             throw MongoDBException::commitInProgress();
417.         }
419.         try {
420.             if ($this->orphanRemovals) {
421.                 foreach ($this->orphanRemovals as $removal) {
422.                     $this->remove($removal);
423.                 }
424.             }
426.             // Raise onFlush
427.             $this->evm->dispatchEvent(Events::onFlush, new Event\OnFlushEventArgs($this->dm));
429.             foreach ($this->getClassesForCommitAction($this->documentUpserts) as $classAndDocuments) {
430.                 [$class, $documents] = $classAndDocuments;
431.                 $this->executeUpserts($class, $documents, $options);
432.             }
434.             foreach ($this->getClassesForCommitAction($this->documentInsertions) as $classAndDocuments) {
435.                 [$class, $documents] = $classAndDocuments;
436.                 $this->executeInserts($class, $documents, $options);
437.             }
439.             foreach ($this->getClassesForCommitAction($this->documentUpdates) as $classAndDocuments) {
440.                 [$class, $documents] = $classAndDocuments;
441.                 $this->executeUpdates($class, $documents, $options);
442.             }
444.             foreach ($this->getClassesForCommitAction($this->documentDeletions, true) as $classAndDocuments) {
445.                 [$class, $documents] = $classAndDocuments;
446.                 $this->executeDeletions($class, $documents, $options);
447.             }
449.             // Raise postFlush
450.             $this->evm->dispatchEvent(Events::postFlush, new Event\PostFlushEventArgs($this->dm));
452.             // Clear up
453.             $this->documentInsertions          =
454.             $this->documentUpserts             =
455.             $this->documentUpdates             =
456.             $this->documentDeletions           =
457.             $this->documentChangeSets          =
458.             $this->collectionUpdates           =
459.             $this->collectionDeletions         =
460.             $this->visitedCollections          =
461.             $this->scheduledForSynchronization =
462.             $this->orphanRemovals              =
463.             $this->hasScheduledCollections     = [];
464.         } finally {
465.             $this->commitsInProgress--;
466.         }
467.     }
469.     /**
470.      * Groups a list of scheduled documents by their class.
471.      *
472.      * @param array<string, object> $documents
473.      *
474.      * @psalm-return array<class-string, array{0: ClassMetadata<object>, 1: array<string, object>}>
475.      */
476.     private function getClassesForCommitAction(array $documents, bool $includeEmbedded = false): array
477.     {
478.         if (empty($documents)) {
479.             return [];
480.         }
482.         $divided = [];
483.         $embeds  = [];
484.         foreach ($documents as $oid => $d) {
485.             $className = get_class($d);
486.             if (isset($embeds[$className])) {
487.                 continue;
488.             }
490.             if (isset($divided[$className])) {
491.                 $divided[$className][1][$oid] = $d;
492.                 continue;
493.             }
495.             $class = $this->dm->getClassMetadata($className);
496.             if ($class->isEmbeddedDocument && ! $includeEmbedded) {
497.                 $embeds[$className] = true;
498.                 continue;
499.             }
501.             if ($class->isView()) {
502.                 continue;
503.             }
505.             if (empty($divided[$class->name])) {
506.                 $divided[$class->name] = [$class, [$oid => $d]];
507.             } else {
508.                 $divided[$class->name][1][$oid] = $d;
509.             }
510.         }
512.         return $divided;
513.     }
515.     /**
516.      * Compute changesets of all documents scheduled for insertion.
517.      *
518.      * Embedded documents will not be processed.
519.      */
520.     private function computeScheduleInsertsChangeSets(): void
521.     {
522.         foreach ($this->documentInsertions as $document) {
523.             $class = $this->dm->getClassMetadata(get_class($document));
524.             if ($class->isEmbeddedDocument || $class->isView()) {
525.                 continue;
526.             }
528.             $this->computeChangeSet($class, $document);
529.         }
530.     }
532.     /**
533.      * Compute changesets of all documents scheduled for upsert.
534.      *
535.      * Embedded documents will not be processed.
536.      */
537.     private function computeScheduleUpsertsChangeSets(): void
538.     {
539.         foreach ($this->documentUpserts as $document) {
540.             $class = $this->dm->getClassMetadata(get_class($document));
541.             if ($class->isEmbeddedDocument || $class->isView()) {
542.                 continue;
543.             }
545.             $this->computeChangeSet($class, $document);
546.         }
547.     }
549.     /**
550.      * Gets the changeset for a document.
551.      *
552.      * @return array array('property' => array(0 => mixed, 1 => mixed))
553.      * @psalm-return array<string, ChangeSet>
554.      */
555.     public function getDocumentChangeSet(object $document): array
556.     {
557.         $oid = spl_object_hash($document);
559.         return $this->documentChangeSets[$oid] ?? [];
560.     }
562.     /**
563.      * Sets the changeset for a document.
564.      *
565.      * @internal
566.      *
567.      * @psalm-param array<string, ChangeSet> $changeset
568.      */
569.     public function setDocumentChangeSet(object $document, array $changeset): void
570.     {
571.         $this->documentChangeSets[spl_object_hash($document)] = $changeset;
572.     }
574.     /**
575.      * Get a documents actual data, flattening all the objects to arrays.
576.      *
577.      * @internal
578.      *
579.      * @return array<string, mixed>
580.      */
581.     public function getDocumentActualData(object $document): array
582.     {
583.         $class      = $this->dm->getClassMetadata(get_class($document));
584.         $actualData = [];
585.         foreach ($class->reflFields as $name => $refProp) {
586.             $mapping = $class->fieldMappings[$name];
587.             // skip not saved fields
588.             if (isset($mapping['notSaved']) && $mapping['notSaved'] === true) {
589.                 continue;
590.             }
592.             $value = $refProp->getValue($document);
593.             if (
594.                 (isset($mapping['association']) && $mapping['type'] === ClassMetadata::MANY)
595.                 && $value !== null && ! ($value instanceof PersistentCollectionInterface)
596.             ) {
597.                 // If $actualData[$name] is not a Collection then use an ArrayCollection.
598.                 if (! $value instanceof Collection) {
599.                     $value = new ArrayCollection($value);
600.                 }
602.                 // Inject PersistentCollection
603.                 $coll = $this->dm->getConfiguration()->getPersistentCollectionFactory()->create($this->dm, $mapping, $value);
604.                 $coll->setOwner($document, $mapping);
605.                 $coll->setDirty(! $value->isEmpty());
606.                 $class->reflFields[$name]->setValue($document, $coll);
607.                 $actualData[$name] = $coll;
608.             } else {
609.                 $actualData[$name] = $value;
610.             }
611.         }
613.         return $actualData;
614.     }
616.     /**
617.      * Computes the changes that happened to a single document.
618.      *
619.      * Modifies/populates the following properties:
620.      *
621.      * {@link originalDocumentData}
622.      * If the document is NEW or MANAGED but not yet fully persisted (only has an id)
623.      * then it was not fetched from the database and therefore we have no original
624.      * document data yet. All of the current document data is stored as the original document data.
625.      *
626.      * {@link documentChangeSets}
627.      * The changes detected on all properties of the document are stored there.
628.      * A change is a tuple array where the first entry is the old value and the second
629.      * entry is the new value of the property. Changesets are used by persisters
630.      * to INSERT/UPDATE the persistent document state.
631.      *
632.      * {@link documentUpdates}
633.      * If the document is already fully MANAGED (has been fetched from the database before)
634.      * and any changes to its properties are detected, then a reference to the document is stored
635.      * there to mark it for an update.
636.      *
637.      * @psalm-param ClassMetadata<T> $class
638.      * @psalm-param T $document
639.      *
640.      * @template T of object
641.      */
642.     public function computeChangeSet(ClassMetadata $class, object $document): void
643.     {
644.         if (! $class->isInheritanceTypeNone()) {
645.             $class = $this->dm->getClassMetadata(get_class($document));
646.         }
648.         // Fire PreFlush lifecycle callbacks
649.         if (! empty($class->lifecycleCallbacks[Events::preFlush])) {
650.             $class->invokeLifecycleCallbacks(Events::preFlush, $document, [new Event\PreFlushEventArgs($this->dm)]);
651.         }
653.         $this->computeOrRecomputeChangeSet($class, $document);
654.     }
656.     /**
657.      * Used to do the common work of computeChangeSet and recomputeSingleDocumentChangeSet
658.      *
659.      * @psalm-param ClassMetadata<T> $class
660.      * @psalm-param T $document
661.      *
662.      * @template T of object
663.      */
664.     private function computeOrRecomputeChangeSet(ClassMetadata $class, object $document, bool $recompute = false): void
665.     {
666.         if ($class->isView()) {
667.             return;
668.         }
670.         $oid           = spl_object_hash($document);
671.         $actualData    = $this->getDocumentActualData($document);
672.         $isNewDocument = ! isset($this->originalDocumentData[$oid]);
673.         if ($isNewDocument) {
674.             // Document is either NEW or MANAGED but not yet fully persisted (only has an id).
675.             // These result in an INSERT.
676.             $this->originalDocumentData[$oid] = $actualData;
677.             $changeSet                        = [];
678.             foreach ($actualData as $propName => $actualValue) {
679.                 /* At this PersistentCollection shouldn't be here, probably it
680.                  * was cloned and its ownership must be fixed
681.                  */
682.                 if ($actualValue instanceof PersistentCollectionInterface && $actualValue->getOwner() !== $document) {
683.                     $actualData[$propName] = $this->fixPersistentCollectionOwnership($actualValue, $document, $class, $propName);
684.                     $actualValue           = $actualData[$propName];
685.                 }
687.                 // ignore inverse side of reference relationship
688.                 if (isset($class->fieldMappings[$propName]['reference']) && $class->fieldMappings[$propName]['isInverseSide']) {
689.                     continue;
690.                 }
692.                 $changeSet[$propName] = [null, $actualValue];
693.             }
695.             $this->documentChangeSets[$oid] = $changeSet;
696.         } else {
697.             if ($class->isReadOnly) {
698.                 return;
699.             }
701.             // Document is "fully" MANAGED: it was already fully persisted before
702.             // and we have a copy of the original data
703.             $originalData           = $this->originalDocumentData[$oid];
704.             $isChangeTrackingNotify = $class->isChangeTrackingNotify();
705.             if ($isChangeTrackingNotify && ! $recompute && isset($this->documentChangeSets[$oid])) {
706.                 $changeSet = $this->documentChangeSets[$oid];
707.             } else {
708.                 $changeSet = [];
709.             }
711.             $gridFSMetadataProperty = null;
713.             if ($class->isFile) {
714.                 try {
715.                     $gridFSMetadata         = $class->getFieldMappingByDbFieldName('metadata');
716.                     $gridFSMetadataProperty = $gridFSMetadata['fieldName'];
717.                 } catch (MappingException $e) {
718.                 }
719.             }
721.             foreach ($actualData as $propName => $actualValue) {
722.                 // skip not saved fields
723.                 if (
724.                     (isset($class->fieldMappings[$propName]['notSaved']) && $class->fieldMappings[$propName]['notSaved'] === true) ||
725.                     ($class->isFile && $propName !== $gridFSMetadataProperty)
726.                 ) {
727.                     continue;
728.                 }
730.                 $orgValue = $originalData[$propName] ?? null;
732.                 // skip if value has not changed
733.                 if ($orgValue === $actualValue) {
734.                     if (! $actualValue instanceof PersistentCollectionInterface) {
735.                         continue;
736.                     }
738.                     if (! $actualValue->isDirty() && ! $this->isCollectionScheduledForDeletion($actualValue)) {
739.                         // consider dirty collections as changed as well
740.                         continue;
741.                     }
742.                 }
744.                 // if relationship is a embed-one, schedule orphan removal to trigger cascade remove operations
745.                 if (isset($class->fieldMappings[$propName]['embedded']) && $class->fieldMappings[$propName]['type'] === ClassMetadata::ONE) {
746.                     if ($orgValue !== null) {
747.                         $this->scheduleOrphanRemoval($orgValue);
748.                     }
750.                     $changeSet[$propName] = [$orgValue, $actualValue];
751.                     continue;
752.                 }
754.                 // if owning side of reference-one relationship
755.                 if (isset($class->fieldMappings[$propName]['reference']) && $class->fieldMappings[$propName]['type'] === ClassMetadata::ONE && $class->fieldMappings[$propName]['isOwningSide']) {
756.                     if ($orgValue !== null && $class->fieldMappings[$propName]['orphanRemoval']) {
757.                         $this->scheduleOrphanRemoval($orgValue);
758.                     }
760.                     $changeSet[$propName] = [$orgValue, $actualValue];
761.                     continue;
762.                 }
764.                 if ($isChangeTrackingNotify) {
765.                     continue;
766.                 }
768.                 // ignore inverse side of reference relationship
769.                 if (isset($class->fieldMappings[$propName]['reference']) && $class->fieldMappings[$propName]['isInverseSide']) {
770.                     continue;
771.                 }
773.                 // Persistent collection was exchanged with the "originally"
774.                 // created one. This can only mean it was cloned and replaced
775.                 // on another document.
776.                 if ($actualValue instanceof PersistentCollectionInterface && $actualValue->getOwner() !== $document) {
777.                     $actualValue = $this->fixPersistentCollectionOwnership($actualValue, $document, $class, $propName);
778.                 }
780.                 // if embed-many or reference-many relationship
781.                 if (isset($class->fieldMappings[$propName]['type']) && $class->fieldMappings[$propName]['type'] === ClassMetadata::MANY) {
782.                     $changeSet[$propName] = [$orgValue, $actualValue];
783.                     /* If original collection was exchanged with a non-empty value
784.                      * and $set will be issued, there is no need to $unset it first
785.                      */
786.                     if ($actualValue && $actualValue->isDirty() && CollectionHelper::usesSet($class->fieldMappings[$propName]['strategy'])) {
787.                         continue;
788.                     }
790.                     if ($orgValue !== $actualValue && $orgValue instanceof PersistentCollectionInterface) {
791.                         $this->scheduleCollectionDeletion($orgValue);
792.                     }
794.                     continue;
795.                 }
797.                 // skip equivalent date values
798.                 if (isset($class->fieldMappings[$propName]['type']) && $class->fieldMappings[$propName]['type'] === 'date') {
799.                     $dateType = Type::getType('date');
800.                     assert($dateType instanceof DateType);
801.                     $dbOrgValue    = $dateType->convertToDatabaseValue($orgValue);
802.                     $dbActualValue = $dateType->convertToDatabaseValue($actualValue);
804.                     $orgTimestamp    = $dbOrgValue instanceof UTCDateTime ? $dbOrgValue->toDateTime()->getTimestamp() : null;
805.                     $actualTimestamp = $dbActualValue instanceof UTCDateTime ? $dbActualValue->toDateTime()->getTimestamp() : null;
807.                     if ($orgTimestamp === $actualTimestamp) {
808.                         continue;
809.                     }
810.                 }
812.                 // regular field
813.                 $changeSet[$propName] = [$orgValue, $actualValue];
814.             }
816.             if ($changeSet) {
817.                 $this->documentChangeSets[$oid] = isset($this->documentChangeSets[$oid])
818.                     ? $changeSet + $this->documentChangeSets[$oid]
819.                     : $changeSet;
821.                 $this->originalDocumentData[$oid] = $actualData;
822.                 $this->scheduleForUpdate($document);
823.             }
824.         }
826.         // Look for changes in associations of the document
827.         $associationMappings = array_filter(
828.             $class->associationMappings,
829.             static fn ($assoc) => empty($assoc['notSaved'])
830.         );
832.         foreach ($associationMappings as $mapping) {
833.             $value = $class->reflFields[$mapping['fieldName']]->getValue($document);
835.             if ($value === null) {
836.                 continue;
837.             }
839.             $this->computeAssociationChanges($document, $mapping, $value);
841.             if (isset($mapping['reference'])) {
842.                 continue;
843.             }
845.             $values = $mapping['type'] === ClassMetadata::ONE ? [$value] : $value->unwrap();
847.             foreach ($values as $obj) {
848.                 $oid2 = spl_object_hash($obj);
850.                 if (! isset($this->documentChangeSets[$oid2])) {
851.                     continue;
852.                 }
854.                 if (empty($this->documentChangeSets[$oid][$mapping['fieldName']])) {
855.                     // instance of $value is the same as it was previously otherwise there would be
856.                     // change set already in place
857.                     $this->documentChangeSets[$oid][$mapping['fieldName']] = [$value, $value];
858.                 }
860.                 if (! $isNewDocument) {
861.                     $this->scheduleForUpdate($document);
862.                 }
864.                 break;
865.             }
866.         }
867.     }
869.     /**
870.      * Computes all the changes that have been done to documents and collections
871.      * since the last commit and stores these changes in the _documentChangeSet map
872.      * temporarily for access by the persisters, until the UoW commit is finished.
873.      */
874.     public function computeChangeSets(): void
875.     {
876.         $this->computeScheduleInsertsChangeSets();
877.         $this->computeScheduleUpsertsChangeSets();
879.         // Compute changes for other MANAGED documents. Change tracking policies take effect here.
880.         foreach ($this->identityMap as $className => $documents) {
881.             $class = $this->dm->getClassMetadata($className);
882.             if ($class->isEmbeddedDocument || $class->isView()) {
883.                 /* we do not want to compute changes to embedded documents up front
884.                  * in case embedded document was replaced and its changeset
885.                  * would corrupt data. Embedded documents' change set will
886.                  * be calculated by reachability from owning document.
887.                  */
888.                 continue;
889.             }
891.             // If change tracking is explicit or happens through notification, then only compute
892.             // changes on document of that type that are explicitly marked for synchronization.
893.             switch (true) {
894.                 case $class->isChangeTrackingDeferredImplicit():
895.                     $documentsToProcess = $documents;
896.                     break;
898.                 case isset($this->scheduledForSynchronization[$className]):
899.                     $documentsToProcess = $this->scheduledForSynchronization[$className];
900.                     break;
902.                 default:
903.                     $documentsToProcess = [];
904.             }
906.             foreach ($documentsToProcess as $document) {
907.                 // Ignore uninitialized proxy objects
908.                 if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
909.                     continue;
910.                 }
912.                 // Only MANAGED documents that are NOT SCHEDULED FOR INSERTION, UPSERT OR DELETION are processed here.
913.                 $oid = spl_object_hash($document);
914.                 if (
915.                     isset($this->documentInsertions[$oid])
916.                     || isset($this->documentUpserts[$oid])
917.                     || isset($this->documentDeletions[$oid])
918.                     || ! isset($this->documentStates[$oid])
919.                 ) {
920.                     continue;
921.                 }
923.                 $this->computeChangeSet($class, $document);
924.             }
925.         }
926.     }
928.     /**
929.      * Computes the changes of an association.
930.      *
931.      * @param mixed $value The value of the association.
932.      * @psalm-param AssociationFieldMapping $assoc
933.      *
934.      * @throws InvalidArgumentException
935.      */
936.     private function computeAssociationChanges(object $parentDocument, array $assoc, $value): void
937.     {
938.         $isNewParentDocument   = isset($this->documentInsertions[spl_object_hash($parentDocument)]);
939.         $class                 = $this->dm->getClassMetadata(get_class($parentDocument));
940.         $topOrExistingDocument = ( ! $isNewParentDocument || ! $class->isEmbeddedDocument);
942.         if ($value instanceof GhostObjectInterface && ! $value->isProxyInitialized()) {
943.             return;
944.         }
946.         if ($value instanceof PersistentCollectionInterface && $value->isDirty() && $value->getOwner() !== null && ($assoc['isOwningSide'] || isset($assoc['embedded']))) {
947.             if ($topOrExistingDocument || CollectionHelper::usesSet($assoc['strategy'])) {
948.                 $this->scheduleCollectionUpdate($value);
949.             }
951.             $topmostOwner                                               = $this->getOwningDocument($value->getOwner());
952.             $this->visitedCollections[spl_object_hash($topmostOwner)][] = $value;
953.             if (! empty($assoc['orphanRemoval']) || isset($assoc['embedded'])) {
954.                 $value->initialize();
955.                 foreach ($value->getDeletedDocuments() as $orphan) {
956.                     $this->scheduleOrphanRemoval($orphan);
957.                 }
958.             }
959.         }
961.         // Look through the documents, and in any of their associations,
962.         // for transient (new) documents, recursively. ("Persistence by reachability")
963.         // Unwrap. Uninitialized collections will simply be empty.
964.         $unwrappedValue = $assoc['type'] === ClassMetadata::ONE ? [$value] : $value->unwrap();
966.         $count = 0;
967.         foreach ($unwrappedValue as $key => $entry) {
968.             if (! is_object($entry)) {
969.                 throw new InvalidArgumentException(
970.                     sprintf('Expected object, found "%s" in %s::%s', $entry, get_class($parentDocument), $assoc['name']),
971.                 );
972.             }
974.             $targetClass = $this->dm->getClassMetadata(get_class($entry));
976.             $state = $this->getDocumentState($entry, self::STATE_NEW);
978.             // Handle "set" strategy for multi-level hierarchy
979.             $pathKey = ! isset($assoc['strategy']) || CollectionHelper::isList($assoc['strategy']) ? $count : $key;
980.             $path    = $assoc['type'] === ClassMetadata::MANY ? $assoc['name'] . '.' . $pathKey : $assoc['name'];
982.             $count++;
984.             switch ($state) {
985.                 case self::STATE_NEW:
986.                     if (! $assoc['isCascadePersist']) {
987.                         throw new InvalidArgumentException('A new document was found through a relationship that was not'
988.                             . ' configured to cascade persist operations: ' . $this->objToStr($entry) . '.'
989.                             . ' Explicitly persist the new document or configure cascading persist operations'
990.                             . ' on the relationship.');
991.                     }
993.                     $this->persistNew($targetClass, $entry);
994.                     $this->setParentAssociation($entry, $assoc, $parentDocument, $path);
995.                     $this->computeChangeSet($targetClass, $entry);
996.                     break;
998.                 case self::STATE_MANAGED:
999.                     if ($targetClass->isEmbeddedDocument) {
1000.                         [, $knownParent] = $this->getParentAssociation($entry);
1001.                         if ($knownParent && $knownParent !== $parentDocument) {
1002.                             $entry = clone $entry;
1003.                             if ($assoc['type'] === ClassMetadata::ONE) {
1004.                                 $class->setFieldValue($parentDocument, $assoc['fieldName'], $entry);
1005.                                 $this->setOriginalDocumentProperty(spl_object_hash($parentDocument), $assoc['fieldName'], $entry);
1006.                                 $poid = spl_object_hash($parentDocument);
1007.                                 if (isset($this->documentChangeSets[$poid][$assoc['fieldName']])) {
1008.                                     $this->documentChangeSets[$poid][$assoc['fieldName']][1] = $entry;
1009.                                 }
1010.                             } else {
1011.                                 // must use unwrapped value to not trigger orphan removal
1012.                                 $unwrappedValue[$key] = $entry;
1013.                             }
1015.                             $this->persistNew($targetClass, $entry);
1016.                         }
1018.                         $this->setParentAssociation($entry, $assoc, $parentDocument, $path);
1019.                         $this->computeChangeSet($targetClass, $entry);
1020.                     }
1022.                     break;
1024.                 case self::STATE_REMOVED:
1025.                     // Consume the $value as array (it's either an array or an ArrayAccess)
1026.                     // and remove the element from Collection.
1027.                     if ($assoc['type'] === ClassMetadata::MANY) {
1028.                         unset($value[$key]);
1029.                     }
1031.                     break;
1033.                 case self::STATE_DETACHED:
1034.                     // Can actually not happen right now as we assume STATE_NEW,
1035.                     // so the exception will be raised from the DBAL layer (constraint violation).
1036.                     throw new InvalidArgumentException('A detached document was found through a '
1037.                         . 'relationship during cascading a persist operation.');
1039.                 default:
1040.                     // MANAGED associated documents are already taken into account
1041.                     // during changeset calculation anyway, since they are in the identity map.
1042.             }
1043.         }
1044.     }
1046.     /**
1047.      * Computes the changeset of an individual document, independently of the
1048.      * computeChangeSets() routine that is used at the beginning of a UnitOfWork#commit().
1049.      *
1050.      * The passed document must be a managed document. If the document already has a change set
1051.      * because this method is invoked during a commit cycle then the change sets are added.
1052.      * whereby changes detected in this method prevail.
1053.      *
1054.      * @psalm-param ClassMetadata<T> $class
1055.      * @psalm-param T $document
1056.      *
1057.      * @throws InvalidArgumentException If the passed document is not MANAGED.
1058.      *
1059.      * @template T of object
1060.      */
1061.     public function recomputeSingleDocumentChangeSet(ClassMetadata $class, object $document): void
1062.     {
1063.         // Ignore uninitialized proxy objects
1064.         if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
1065.             return;
1066.         }
1068.         $oid = spl_object_hash($document);
1070.         if (! isset($this->documentStates[$oid]) || $this->documentStates[$oid] !== self::STATE_MANAGED) {
1071.             throw new InvalidArgumentException('Document must be managed.');
1072.         }
1074.         if (! $class->isInheritanceTypeNone()) {
1075.             $class = $this->dm->getClassMetadata(get_class($document));
1076.         }
1078.         $this->computeOrRecomputeChangeSet($class, $document, true);
1079.     }
1081.     /**
1082.      * @psalm-param ClassMetadata<T> $class
1083.      * @psalm-param T $document
1084.      *
1085.      * @throws InvalidArgumentException If there is something wrong with document's identifier.
1086.      *
1087.      * @template T of object
1088.      */
1089.     private function persistNew(ClassMetadata $class, object $document): void
1090.     {
1091.         $this->lifecycleEventManager->prePersist($class, $document);
1092.         $oid    = spl_object_hash($document);
1093.         $upsert = false;
1094.         if ($class->identifier) {
1095.             $idValue = $class->getIdentifierValue($document);
1096.             $upsert  = ! $class->isEmbeddedDocument && $idValue !== null;
1098.             if ($class->generatorType === ClassMetadata::GENERATOR_TYPE_NONE && $idValue === null) {
1099.                 throw new InvalidArgumentException(sprintf(
1100.                     '%s uses NONE identifier generation strategy but no identifier was provided when persisting.',
1101.                     get_class($document),
1102.                 ));
1103.             }
1105.             if ($class->generatorType === ClassMetadata::GENERATOR_TYPE_AUTO && $idValue !== null && ! preg_match('#^[0-9a-f]{24}$#', (string) $idValue)) {
1106.                 throw new InvalidArgumentException(sprintf(
1107.                     '%s uses AUTO identifier generation strategy but provided identifier is not a valid ObjectId.',
1108.                     get_class($document),
1109.                 ));
1110.             }
1112.             if ($class->generatorType !== ClassMetadata::GENERATOR_TYPE_NONE && $idValue === null && $class->idGenerator !== null) {
1113.                 $idValue = $class->idGenerator->generate($this->dm, $document);
1114.                 $idValue = $class->getPHPIdentifierValue($class->getDatabaseIdentifierValue($idValue));
1115.                 $class->setIdentifierValue($document, $idValue);
1116.             }
1118.             $this->documentIdentifiers[$oid] = $idValue;
1119.         } else {
1120.             // this is for embedded documents without identifiers
1121.             $this->documentIdentifiers[$oid] = $oid;
1122.         }
1124.         $this->documentStates[$oid] = self::STATE_MANAGED;
1126.         if ($upsert) {
1127.             $this->scheduleForUpsert($class, $document);
1128.         } else {
1129.             $this->scheduleForInsert($class, $document);
1130.         }
1131.     }
1133.     /**
1134.      * Executes all document insertions for documents of the specified type.
1135.      *
1136.      * @psalm-param ClassMetadata<T> $class
1137.      * @psalm-param T[] $documents
1138.      * @psalm-param CommitOptions $options
1139.      *
1140.      * @template T of object
1141.      */
1142.     private function executeInserts(ClassMetadata $class, array $documents, array $options = []): void
1143.     {
1144.         $persister = $this->getDocumentPersister($class->name);
1146.         foreach ($documents as $oid => $document) {
1147.             $persister->addInsert($document);
1148.             unset($this->documentInsertions[$oid]);
1149.         }
1151.         $persister->executeInserts($options);
1153.         foreach ($documents as $document) {
1154.             $this->lifecycleEventManager->postPersist($class, $document);
1155.         }
1156.     }
1158.     /**
1159.      * Executes all document upserts for documents of the specified type.
1160.      *
1161.      * @psalm-param ClassMetadata<T> $class
1162.      * @psalm-param T[] $documents
1163.      * @psalm-param CommitOptions $options
1164.      *
1165.      * @template T of object
1166.      */
1167.     private function executeUpserts(ClassMetadata $class, array $documents, array $options = []): void
1168.     {
1169.         $persister = $this->getDocumentPersister($class->name);
1171.         foreach ($documents as $oid => $document) {
1172.             $persister->addUpsert($document);
1173.             unset($this->documentUpserts[$oid]);
1174.         }
1176.         $persister->executeUpserts($options);
1178.         foreach ($documents as $document) {
1179.             $this->lifecycleEventManager->postPersist($class, $document);
1180.         }
1181.     }
1183.     /**
1184.      * Executes all document updates for documents of the specified type.
1185.      *
1186.      * @psalm-param ClassMetadata<T> $class
1187.      * @psalm-param T[] $documents
1188.      * @psalm-param CommitOptions $options
1189.      *
1190.      * @template T of object
1191.      */
1192.     private function executeUpdates(ClassMetadata $class, array $documents, array $options = []): void
1193.     {
1194.         if ($class->isReadOnly) {
1195.             return;
1196.         }
1198.         $className = $class->name;
1199.         $persister = $this->getDocumentPersister($className);
1201.         foreach ($documents as $oid => $document) {
1202.             $this->lifecycleEventManager->preUpdate($class, $document);
1204.             if (! empty($this->documentChangeSets[$oid]) || $this->hasScheduledCollections($document)) {
1205.                 $persister->update($document, $options);
1206.             }
1208.             unset($this->documentUpdates[$oid]);
1210.             $this->lifecycleEventManager->postUpdate($class, $document);
1211.         }
1212.     }
1214.     /**
1215.      * Executes all document deletions for documents of the specified type.
1216.      *
1217.      * @psalm-param ClassMetadata<T> $class
1218.      * @psalm-param T[] $documents
1219.      * @psalm-param CommitOptions $options
1220.      *
1221.      * @template T of object
1222.      */
1223.     private function executeDeletions(ClassMetadata $class, array $documents, array $options = []): void
1224.     {
1225.         $persister = $this->getDocumentPersister($class->name);
1227.         foreach ($documents as $oid => $document) {
1228.             if (! $class->isEmbeddedDocument) {
1229.                 $persister->delete($document, $options);
1230.             }
1232.             unset(
1233.                 $this->documentDeletions[$oid],
1234.                 $this->documentIdentifiers[$oid],
1235.                 $this->originalDocumentData[$oid],
1236.             );
1238.             // Clear snapshot information for any referenced PersistentCollection
1239.             // http://www.doctrine-project.org/jira/browse/MODM-95
1240.             foreach ($class->associationMappings as $fieldMapping) {
1241.                 if (! isset($fieldMapping['type']) || $fieldMapping['type'] !== ClassMetadata::MANY) {
1242.                     continue;
1243.                 }
1245.                 $value = $class->reflFields[$fieldMapping['fieldName']]->getValue($document);
1246.                 if (! ($value instanceof PersistentCollectionInterface)) {
1247.                     continue;
1248.                 }
1250.                 $value->clearSnapshot();
1251.             }
1253.             // Document with this $oid after deletion treated as NEW, even if the $oid
1254.             // is obtained by a new document because the old one went out of scope.
1255.             $this->documentStates[$oid] = self::STATE_NEW;
1257.             $this->lifecycleEventManager->postRemove($class, $document);
1258.         }
1259.     }
1261.     /**
1262.      * Schedules a document for insertion into the database.
1263.      * If the document already has an identifier, it will be added to the
1264.      * identity map.
1265.      *
1266.      * @internal
1267.      *
1268.      * @psalm-param ClassMetadata<T> $class
1269.      * @psalm-param T $document
1270.      *
1271.      * @throws InvalidArgumentException
1272.      *
1273.      * @template T of object
1274.      */
1275.     public function scheduleForInsert(ClassMetadata $class, object $document): void
1276.     {
1277.         $oid = spl_object_hash($document);
1279.         if (isset($this->documentUpdates[$oid])) {
1280.             throw new InvalidArgumentException('Dirty document can not be scheduled for insertion.');
1281.         }
1283.         if (isset($this->documentDeletions[$oid])) {
1284.             throw new InvalidArgumentException('Removed document can not be scheduled for insertion.');
1285.         }
1287.         if (isset($this->documentInsertions[$oid])) {
1288.             throw new InvalidArgumentException('Document can not be scheduled for insertion twice.');
1289.         }
1291.         $this->documentInsertions[$oid] = $document;
1293.         if (! isset($this->documentIdentifiers[$oid])) {
1294.             return;
1295.         }
1297.         $this->addToIdentityMap($document);
1298.     }
1300.     /**
1301.      * Schedules a document for upsert into the database and adds it to the
1302.      * identity map
1303.      *
1304.      * @internal
1305.      *
1306.      * @psalm-param ClassMetadata<T> $class
1307.      * @psalm-param T $document
1308.      *
1309.      * @throws InvalidArgumentException
1310.      *
1311.      * @template T of object
1312.      */
1313.     public function scheduleForUpsert(ClassMetadata $class, object $document): void
1314.     {
1315.         $oid = spl_object_hash($document);
1317.         if ($class->isEmbeddedDocument) {
1318.             throw new InvalidArgumentException('Embedded document can not be scheduled for upsert.');
1319.         }
1321.         if (isset($this->documentUpdates[$oid])) {
1322.             throw new InvalidArgumentException('Dirty document can not be scheduled for upsert.');
1323.         }
1325.         if (isset($this->documentDeletions[$oid])) {
1326.             throw new InvalidArgumentException('Removed document can not be scheduled for upsert.');
1327.         }
1329.         if (isset($this->documentUpserts[$oid])) {
1330.             throw new InvalidArgumentException('Document can not be scheduled for upsert twice.');
1331.         }
1333.         $this->documentUpserts[$oid]     = $document;
1334.         $this->documentIdentifiers[$oid] = $class->getIdentifierValue($document);
1335.         $this->addToIdentityMap($document);
1336.     }
1338.     /**
1339.      * Checks whether a document is scheduled for insertion.
1340.      */
1341.     public function isScheduledForInsert(object $document): bool
1342.     {
1343.         return isset($this->documentInsertions[spl_object_hash($document)]);
1344.     }
1346.     /**
1347.      * Checks whether a document is scheduled for upsert.
1348.      */
1349.     public function isScheduledForUpsert(object $document): bool
1350.     {
1351.         return isset($this->documentUpserts[spl_object_hash($document)]);
1352.     }
1354.     /**
1355.      * Schedules a document for being updated.
1356.      *
1357.      * @internal
1358.      *
1359.      * @throws InvalidArgumentException
1360.      */
1361.     public function scheduleForUpdate(object $document): void
1362.     {
1363.         $oid = spl_object_hash($document);
1364.         if (! isset($this->documentIdentifiers[$oid])) {
1365.             throw new InvalidArgumentException('Document has no identity.');
1366.         }
1368.         if (isset($this->documentDeletions[$oid])) {
1369.             throw new InvalidArgumentException('Document is removed.');
1370.         }
1372.         if (
1373.             isset($this->documentUpdates[$oid])
1374.             || isset($this->documentInsertions[$oid])
1375.             || isset($this->documentUpserts[$oid])
1376.         ) {
1377.             return;
1378.         }
1380.         $this->documentUpdates[$oid] = $document;
1381.     }
1383.     /**
1384.      * Checks whether a document is registered as dirty in the unit of work.
1385.      * Note: Is not very useful currently as dirty documents are only registered
1386.      * at commit time.
1387.      */
1388.     public function isScheduledForUpdate(object $document): bool
1389.     {
1390.         return isset($this->documentUpdates[spl_object_hash($document)]);
1391.     }
1393.     /**
1394.      * Checks whether a document is registered to be checked in the unit of work.
1395.      */
1396.     public function isScheduledForSynchronization(object $document): bool
1397.     {
1398.         $class = $this->dm->getClassMetadata(get_class($document));
1400.         return isset($this->scheduledForSynchronization[$class->name][spl_object_hash($document)]);
1401.     }
1403.     /**
1404.      * Schedules a document for deletion.
1405.      *
1406.      * @internal
1407.      */
1408.     public function scheduleForDelete(object $document, bool $isView = false): void
1409.     {
1410.         $oid = spl_object_hash($document);
1412.         if (isset($this->documentInsertions[$oid])) {
1413.             if ($this->isInIdentityMap($document)) {
1414.                 $this->removeFromIdentityMap($document);
1415.             }
1417.             unset($this->documentInsertions[$oid]);
1419.             return; // document has not been persisted yet, so nothing more to do.
1420.         }
1422.         if (! $this->isInIdentityMap($document)) {
1423.             return; // ignore
1424.         }
1426.         $this->removeFromIdentityMap($document);
1427.         $this->documentStates[$oid] = self::STATE_REMOVED;
1429.         if (isset($this->documentUpdates[$oid])) {
1430.             unset($this->documentUpdates[$oid]);
1431.         }
1433.         if (isset($this->documentUpserts[$oid])) {
1434.             unset($this->documentUpserts[$oid]);
1435.         }
1437.         if (isset($this->documentDeletions[$oid])) {
1438.             return;
1439.         }
1441.         if ($isView) {
1442.             return;
1443.         }
1445.         $this->documentDeletions[$oid] = $document;
1446.     }
1448.     /**
1449.      * Checks whether a document is registered as removed/deleted with the unit
1450.      * of work.
1451.      */
1452.     public function isScheduledForDelete(object $document): bool
1453.     {
1454.         return isset($this->documentDeletions[spl_object_hash($document)]);
1455.     }
1457.     /**
1458.      * Checks whether a document is scheduled for insertion, update or deletion.
1459.      *
1460.      * @internal
1461.      */
1462.     public function isDocumentScheduled(object $document): bool
1463.     {
1464.         $oid = spl_object_hash($document);
1466.         return isset($this->documentInsertions[$oid]) ||
1467.             isset($this->documentUpserts[$oid]) ||
1468.             isset($this->documentUpdates[$oid]) ||
1469.             isset($this->documentDeletions[$oid]);
1470.     }
1472.     /**
1473.      * Registers a document in the identity map.
1474.      *
1475.      * Note that documents in a hierarchy are registered with the class name of
1476.      * the root document. Identifiers are serialized before being used as array
1477.      * keys to allow differentiation of equal, but not identical, values.
1478.      *
1479.      * @internal
1480.      */
1481.     public function addToIdentityMap(object $document): bool
1482.     {
1483.         $class = $this->dm->getClassMetadata(get_class($document));
1484.         $id    = $this->getIdForIdentityMap($document);
1486.         if (isset($this->identityMap[$class->name][$id])) {
1487.             return false;
1488.         }
1490.         $this->identityMap[$class->name][$id] = $document;
1492.         if (
1493.             $document instanceof NotifyPropertyChanged &&
1494.             ( ! $document instanceof GhostObjectInterface || $document->isProxyInitialized())
1495.         ) {
1496.             $document->addPropertyChangedListener($this);
1497.         }
1499.         return true;
1500.     }
1502.     /**
1503.      * Gets the state of a document with regard to the current unit of work.
1504.      *
1505.      * @param int|null $assume The state to assume if the state is not yet known (not MANAGED or REMOVED).
1506.      *                         This parameter can be set to improve performance of document state detection
1507.      *                         by potentially avoiding a database lookup if the distinction between NEW and DETACHED
1508.      *                         is either known or does not matter for the caller of the method.
1509.      */
1510.     public function getDocumentState(object $document, ?int $assume = null): int
1511.     {
1512.         $oid = spl_object_hash($document);
1514.         if (isset($this->documentStates[$oid])) {
1515.             return $this->documentStates[$oid];
1516.         }
1518.         $class = $this->dm->getClassMetadata(get_class($document));
1520.         if ($class->isEmbeddedDocument) {
1521.             return self::STATE_NEW;
1522.         }
1524.         if ($assume !== null) {
1525.             return $assume;
1526.         }
1528.         /* State can only be NEW or DETACHED, because MANAGED/REMOVED states are
1529.          * known. Note that you cannot remember the NEW or DETACHED state in
1530.          * _documentStates since the UoW does not hold references to such
1531.          * objects and the object hash can be reused. More generally, because
1532.          * the state may "change" between NEW/DETACHED without the UoW being
1533.          * aware of it.
1534.          */
1535.         $id = $class->getIdentifierObject($document);
1537.         if ($id === null) {
1538.             return self::STATE_NEW;
1539.         }
1541.         // Check for a version field, if available, to avoid a DB lookup.
1542.         if ($class->isVersioned && $class->versionField !== null) {
1543.             return $class->getFieldValue($document, $class->versionField)
1544.                 ? self::STATE_DETACHED
1545.                 : self::STATE_NEW;
1546.         }
1548.         // Last try before DB lookup: check the identity map.
1549.         if ($this->tryGetById($id, $class)) {
1550.             return self::STATE_DETACHED;
1551.         }
1553.         // DB lookup
1554.         if ($this->getDocumentPersister($class->name)->exists($document)) {
1555.             return self::STATE_DETACHED;
1556.         }
1558.         return self::STATE_NEW;
1559.     }
1561.     /**
1562.      * Removes a document from the identity map. This effectively detaches the
1563.      * document from the persistence management of Doctrine.
1564.      *
1565.      * @internal
1566.      *
1567.      * @throws InvalidArgumentException
1568.      */
1569.     public function removeFromIdentityMap(object $document): bool
1570.     {
1571.         $oid = spl_object_hash($document);
1573.         // Check if id is registered first
1574.         if (! isset($this->documentIdentifiers[$oid])) {
1575.             return false;
1576.         }
1578.         $class = $this->dm->getClassMetadata(get_class($document));
1579.         $id    = $this->getIdForIdentityMap($document);
1581.         if (isset($this->identityMap[$class->name][$id])) {
1582.             unset($this->identityMap[$class->name][$id]);
1583.             $this->documentStates[$oid] = self::STATE_DETACHED;
1585.             return true;
1586.         }
1588.         return false;
1589.     }
1591.     /**
1592.      * Gets a document in the identity map by its identifier hash.
1593.      *
1594.      * @internal
1595.      *
1596.      * @param mixed $id Document identifier
1597.      * @psalm-param ClassMetadata<T> $class
1598.      *
1599.      * @psalm-return T
1600.      *
1601.      * @throws InvalidArgumentException If the class does not have an identifier.
1602.      *
1603.      * @template T of object
1604.      *
1605.      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
1606.      */
1607.     public function getById($id, ClassMetadata $class): object
1608.     {
1609.         if (! $class->identifier) {
1610.             throw new InvalidArgumentException(sprintf('Class "%s" does not have an identifier', $class->name));
1611.         }
1613.         $serializedId = serialize($class->getDatabaseIdentifierValue($id));
1615.         return $this->identityMap[$class->name][$serializedId];
1616.     }
1618.     /**
1619.      * Tries to get a document by its identifier hash. If no document is found
1620.      * for the given hash, FALSE is returned.
1621.      *
1622.      * @internal
1623.      *
1624.      * @param mixed $id Document identifier
1625.      * @psalm-param ClassMetadata<T> $class
1626.      *
1627.      * @return mixed The found document or FALSE.
1628.      * @psalm-return T|false
1629.      *
1630.      * @throws InvalidArgumentException If the class does not have an identifier.
1631.      *
1632.      * @template T of object
1633.      *
1634.      * @psalm-suppress InvalidReturnStatement, InvalidReturnType because of the inability of defining a generic property map
1635.      */
1636.     public function tryGetById($id, ClassMetadata $class)
1637.     {
1638.         if (! $class->identifier) {
1639.             throw new InvalidArgumentException(sprintf('Class "%s" does not have an identifier', $class->name));
1640.         }
1642.         $serializedId = serialize($class->getDatabaseIdentifierValue($id));
1644.         return $this->identityMap[$class->name][$serializedId] ?? false;
1645.     }
1647.     /**
1648.      * Schedules a document for dirty-checking at commit-time.
1649.      *
1650.      * @internal
1651.      */
1652.     public function scheduleForSynchronization(object $document): void
1653.     {
1654.         $class                                                                       = $this->dm->getClassMetadata(get_class($document));
1655.         $this->scheduledForSynchronization[$class->name][spl_object_hash($document)] = $document;
1656.     }
1658.     /**
1659.      * Checks whether a document is registered in the identity map.
1660.      *
1661.      * @internal
1662.      */
1663.     public function isInIdentityMap(object $document): bool
1664.     {
1665.         $oid = spl_object_hash($document);
1667.         if (! isset($this->documentIdentifiers[$oid])) {
1668.             return false;
1669.         }
1671.         $class = $this->dm->getClassMetadata(get_class($document));
1672.         $id    = $this->getIdForIdentityMap($document);
1674.         return isset($this->identityMap[$class->name][$id]);
1675.     }
1677.     private function getIdForIdentityMap(object $document): string
1678.     {
1679.         $class = $this->dm->getClassMetadata(get_class($document));
1681.         if (! $class->identifier) {
1682.             $id = spl_object_hash($document);
1683.         } else {
1684.             $id = $this->documentIdentifiers[spl_object_hash($document)];
1685.             $id = serialize($class->getDatabaseIdentifierValue($id));
1686.         }
1688.         return $id;
1689.     }
1691.     /**
1692.      * Checks whether an identifier exists in the identity map.
1693.      *
1694.      * @internal
1695.      *
1696.      * @param mixed $id
1697.      */
1698.     public function containsId($id, string $rootClassName): bool
1699.     {
1700.         return isset($this->identityMap[$rootClassName][serialize($id)]);
1701.     }
1703.     /**
1704.      * Persists a document as part of the current unit of work.
1705.      *
1706.      * @internal
1707.      *
1708.      * @throws MongoDBException If trying to persist MappedSuperclass.
1709.      * @throws InvalidArgumentException If there is something wrong with document's identifier.
1710.      */
1711.     public function persist(object $document): void
1712.     {
1713.         $class = $this->dm->getClassMetadata(get_class($document));
1714.         if ($class->isMappedSuperclass || $class->isQueryResultDocument) {
1715.             throw MongoDBException::cannotPersistMappedSuperclass($class->name);
1716.         }
1718.         $visited = [];
1719.         $this->doPersist($document, $visited);
1720.     }
1722.     /**
1723.      * Saves a document as part of the current unit of work.
1724.      * This method is internally called during save() cascades as it tracks
1725.      * the already visited documents to prevent infinite recursions.
1726.      *
1727.      * NOTE: This method always considers documents that are not yet known to
1728.      * this UnitOfWork as NEW.
1729.      *
1730.      * @param array<string, object> $visited
1731.      *
1732.      * @throws InvalidArgumentException
1733.      * @throws MongoDBException
1734.      */
1735.     private function doPersist(object $document, array &$visited): void
1736.     {
1737.         $oid = spl_object_hash($document);
1738.         if (isset($visited[$oid])) {
1739.             return; // Prevent infinite recursion
1740.         }
1742.         $visited[$oid] = $document; // Mark visited
1744.         $class = $this->dm->getClassMetadata(get_class($document));
1746.         $documentState = $this->getDocumentState($document, self::STATE_NEW);
1747.         switch ($documentState) {
1748.             case self::STATE_MANAGED:
1749.                 // Nothing to do, except if policy is "deferred explicit"
1750.                 if ($class->isChangeTrackingDeferredExplicit() && ! $class->isView()) {
1751.                     $this->scheduleForSynchronization($document);
1752.                 }
1754.                 break;
1755.             case self::STATE_NEW:
1756.                 if ($class->isFile) {
1757.                     throw MongoDBException::cannotPersistGridFSFile($class->name);
1758.                 }
1760.                 if ($class->isView()) {
1761.                     return;
1762.                 }
1764.                 $this->persistNew($class, $document);
1765.                 break;
1767.             case self::STATE_REMOVED:
1768.                 // Document becomes managed again
1769.                 unset($this->documentDeletions[$oid]);
1771.                 $this->documentStates[$oid] = self::STATE_MANAGED;
1772.                 break;
1774.             case self::STATE_DETACHED:
1775.                 throw new InvalidArgumentException(
1776.                     'Behavior of persist() for a detached document is not yet defined.',
1777.                 );
1779.             default:
1780.                 throw MongoDBException::invalidDocumentState($documentState);
1781.         }
1783.         $this->cascadePersist($document, $visited);
1784.     }
1786.     /**
1787.      * Deletes a document as part of the current unit of work.
1788.      *
1789.      * @internal
1790.      */
1791.     public function remove(object $document): void
1792.     {
1793.         $visited = [];
1794.         $this->doRemove($document, $visited);
1795.     }
1797.     /**
1798.      * Deletes a document as part of the current unit of work.
1799.      *
1800.      * This method is internally called during delete() cascades as it tracks
1801.      * the already visited documents to prevent infinite recursions.
1802.      *
1803.      * @param array<string, object> $visited
1804.      *
1805.      * @throws MongoDBException
1806.      */
1807.     private function doRemove(object $document, array &$visited): void
1808.     {
1809.         $oid = spl_object_hash($document);
1810.         if (isset($visited[$oid])) {
1811.             return; // Prevent infinite recursion
1812.         }
1814.         $visited[$oid] = $document; // mark visited
1816.         /* Cascade first, because scheduleForDelete() removes the entity from
1817.          * the identity map, which can cause problems when a lazy Proxy has to
1818.          * be initialized for the cascade operation.
1819.          */
1820.         $this->cascadeRemove($document, $visited);
1822.         $class         = $this->dm->getClassMetadata(get_class($document));
1823.         $documentState = $this->getDocumentState($document);
1824.         switch ($documentState) {
1825.             case self::STATE_NEW:
1826.             case self::STATE_REMOVED:
1827.                 // nothing to do
1828.                 break;
1829.             case self::STATE_MANAGED:
1830.                 $this->lifecycleEventManager->preRemove($class, $document);
1831.                 $this->scheduleForDelete($document, $class->isView());
1832.                 break;
1833.             case self::STATE_DETACHED:
1834.                 throw MongoDBException::detachedDocumentCannotBeRemoved();
1836.             default:
1837.                 throw MongoDBException::invalidDocumentState($documentState);
1838.         }
1839.     }
1841.     /**
1842.      * Merges the state of the given detached document into this UnitOfWork.
1843.      *
1844.      * @internal
1845.      */
1846.     public function merge(object $document): object
1847.     {
1848.         $visited = [];
1850.         return $this->doMerge($document, $visited);
1851.     }
1853.     /**
1854.      * Executes a merge operation on a document.
1855.      *
1856.      * @param array<string, object> $visited
1857.      * @psalm-param AssociationFieldMapping|null $assoc
1858.      *
1859.      * @throws InvalidArgumentException If the entity instance is NEW.
1860.      * @throws LockException If the document uses optimistic locking through a
1861.      *                       version attribute and the version check against the
1862.      *                       managed copy fails.
1863.      */
1864.     private function doMerge(object $document, array &$visited, ?object $prevManagedCopy = null, ?array $assoc = null): object
1865.     {
1866.         $oid = spl_object_hash($document);
1868.         if (isset($visited[$oid])) {
1869.             return $visited[$oid]; // Prevent infinite recursion
1870.         }
1872.         $visited[$oid] = $document; // mark visited
1874.         $class = $this->dm->getClassMetadata(get_class($document));
1876.         /* First we assume DETACHED, although it can still be NEW but we can
1877.          * avoid an extra DB round trip this way. If it is not MANAGED but has
1878.          * an identity, we need to fetch it from the DB anyway in order to
1879.          * merge. MANAGED documents are ignored by the merge operation.
1880.          */
1881.         $managedCopy = $document;
1883.         if ($this->getDocumentState($document, self::STATE_DETACHED) !== self::STATE_MANAGED) {
1884.             if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
1885.                 $document->initializeProxy();
1886.             }
1888.             $identifier = $class->getIdentifier();
1889.             // We always have one element in the identifier array but it might be null
1890.             $id          = $identifier[0] !== null ? $class->getIdentifierObject($document) : null;
1891.             $managedCopy = null;
1893.             // Try to fetch document from the database
1894.             if (! $class->isEmbeddedDocument && $id !== null) {
1895.                 $managedCopy = $this->dm->find($class->name, $id);
1897.                 // Managed copy may be removed in which case we can't merge
1898.                 if ($managedCopy && $this->getDocumentState($managedCopy) === self::STATE_REMOVED) {
1899.                     throw new InvalidArgumentException('Removed entity detected during merge. Cannot merge with a removed entity.');
1900.                 }
1902.                 if ($managedCopy instanceof GhostObjectInterface && ! $managedCopy->isProxyInitialized()) {
1903.                     $managedCopy->initializeProxy();
1904.                 }
1905.             }
1907.             if ($managedCopy === null) {
1908.                 // Create a new managed instance
1909.                 $managedCopy = $class->newInstance();
1910.                 if ($id !== null) {
1911.                     $class->setIdentifierValue($managedCopy, $id);
1912.                 }
1914.                 $this->persistNew($class, $managedCopy);
1915.             }
1917.             if ($class->isVersioned) {
1918.                 $managedCopyVersion = $class->reflFields[$class->versionField]->getValue($managedCopy);
1919.                 $documentVersion    = $class->reflFields[$class->versionField]->getValue($document);
1921.                 // Throw exception if versions don't match
1922.                 if ($managedCopyVersion !== $documentVersion) {
1923.                     throw LockException::lockFailedVersionMissmatch($document, $documentVersion, $managedCopyVersion);
1924.                 }
1925.             }
1927.             // Merge state of $document into existing (managed) document
1928.             foreach ($class->reflClass->getProperties() as $nativeReflection) {
1929.                 $name = $nativeReflection->name;
1930.                 $prop = $this->reflectionService->getAccessibleProperty($class->name, $name);
1931.                 assert($prop instanceof ReflectionProperty);
1933.                 if (method_exists($prop, 'isInitialized') && ! $prop->isInitialized($document)) {
1934.                     continue;
1935.                 }
1937.                 if (! isset($class->associationMappings[$name])) {
1938.                     if (! $class->isIdentifier($name)) {
1939.                         $prop->setValue($managedCopy, $prop->getValue($document));
1940.                     }
1941.                 } else {
1942.                     $assoc2 = $class->associationMappings[$name];
1944.                     if ($assoc2['type'] === ClassMetadata::ONE) {
1945.                         $other = $prop->getValue($document);
1947.                         if ($other === null) {
1948.                             $prop->setValue($managedCopy, null);
1949.                         } elseif ($other instanceof GhostObjectInterface && ! $other->isProxyInitialized()) {
1950.                             // Do not merge fields marked lazy that have not been fetched
1951.                             continue;
1952.                         } elseif (! $assoc2['isCascadeMerge']) {
1953.                             if ($this->getDocumentState($other) === self::STATE_DETACHED) {
1954.                                 $targetDocument = $assoc2['targetDocument'] ?? get_class($other);
1955.                                 $targetClass    = $this->dm->getClassMetadata($targetDocument);
1956.                                 $relatedId      = $targetClass->getIdentifierObject($other);
1958.                                 $current = $prop->getValue($managedCopy);
1959.                                 if ($current !== null) {
1960.                                     $this->removeFromIdentityMap($current);
1961.                                 }
1963.                                 if ($targetClass->subClasses) {
1964.                                     $other = $this->dm->find($targetClass->name, $relatedId);
1965.                                 } else {
1966.                                     $other = $this
1967.                                         ->dm
1968.                                         ->getProxyFactory()
1969.                                         ->getProxy($targetClass, $relatedId);
1970.                                     $this->registerManaged($other, $relatedId, []);
1971.                                 }
1972.                             }
1974.                             $prop->setValue($managedCopy, $other);
1975.                         }
1976.                     } else {
1977.                         $mergeCol = $prop->getValue($document);
1979.                         if ($mergeCol instanceof PersistentCollectionInterface && ! $mergeCol->isInitialized() && ! $assoc2['isCascadeMerge']) {
1980.                             /* Do not merge fields marked lazy that have not
1981.                              * been fetched. Keep the lazy persistent collection
1982.                              * of the managed copy.
1983.                              */
1984.                             continue;
1985.                         }
1987.                         $managedCol = $prop->getValue($managedCopy);
1989.                         if (! $managedCol) {
1990.                             $managedCol = $this->dm->getConfiguration()->getPersistentCollectionFactory()->create($this->dm, $assoc2, null);
1991.                             $managedCol->setOwner($managedCopy, $assoc2);
1992.                             $prop->setValue($managedCopy, $managedCol);
1993.                             $this->originalDocumentData[$oid][$name] = $managedCol;
1994.                         }
1996.                         /* Note: do not process association's target documents.
1997.                          * They will be handled during the cascade. Initialize
1998.                          * and, if necessary, clear $managedCol for now.
1999.                          */
2000.                         if ($assoc2['isCascadeMerge']) {
2001.                             $managedCol->initialize();
2003.                             // If $managedCol differs from the merged collection, clear and set dirty
2004.                             if (! $managedCol->isEmpty() && $managedCol !== $mergeCol) {
2005.                                 $managedCol->unwrap()->clear();
2006.                                 $managedCol->setDirty(true);
2008.                                 if ($assoc2['isOwningSide'] && $class->isChangeTrackingNotify()) {
2009.                                     $this->scheduleForSynchronization($managedCopy);
2010.                                 }
2011.                             }
2012.                         }
2013.                     }
2014.                 }
2016.                 if (! $class->isChangeTrackingNotify()) {
2017.                     continue;
2018.                 }
2020.                 // Just treat all properties as changed, there is no other choice.
2021.                 $this->propertyChanged($managedCopy, $name, null, $prop->getValue($managedCopy));
2022.             }
2024.             if ($class->isChangeTrackingDeferredExplicit()) {
2025.                 $this->scheduleForSynchronization($document);
2026.             }
2027.         }
2029.         if ($prevManagedCopy !== null) {
2030.             $assocField = $assoc['fieldName'];
2031.             $prevClass  = $this->dm->getClassMetadata(get_class($prevManagedCopy));
2033.             if ($assoc['type'] === ClassMetadata::ONE) {
2034.                 $prevClass->reflFields[$assocField]->setValue($prevManagedCopy, $managedCopy);
2035.             } else {
2036.                 $prevClass->reflFields[$assocField]->getValue($prevManagedCopy)->add($managedCopy);
2038.                 if ($assoc['type'] === ClassMetadata::MANY && isset($assoc['mappedBy'])) {
2039.                     $class->reflFields[$assoc['mappedBy']]->setValue($managedCopy, $prevManagedCopy);
2040.                 }
2041.             }
2042.         }
2044.         // Mark the managed copy visited as well
2045.         $visited[spl_object_hash($managedCopy)] = $managedCopy;
2047.         $this->cascadeMerge($document, $managedCopy, $visited);
2049.         return $managedCopy;
2050.     }
2052.     /**
2053.      * Detaches a document from the persistence management. It's persistence will
2054.      * no longer be managed by Doctrine.
2055.      *
2056.      * @internal
2057.      */
2058.     public function detach(object $document): void
2059.     {
2060.         $visited = [];
2061.         $this->doDetach($document, $visited);
2062.     }
2064.     /**
2065.      * Executes a detach operation on the given document.
2066.      *
2067.      * @param array<string, object> $visited
2068.      */
2069.     private function doDetach(object $document, array &$visited): void
2070.     {
2071.         $oid = spl_object_hash($document);
2072.         if (isset($visited[$oid])) {
2073.             return; // Prevent infinite recursion
2074.         }
2076.         $visited[$oid] = $document; // mark visited
2078.         switch ($this->getDocumentState($document, self::STATE_DETACHED)) {
2079.             case self::STATE_MANAGED:
2080.                 $this->removeFromIdentityMap($document);
2081.                 unset(
2082.                     $this->documentInsertions[$oid],
2083.                     $this->documentUpdates[$oid],
2084.                     $this->documentDeletions[$oid],
2085.                     $this->documentIdentifiers[$oid],
2086.                     $this->documentStates[$oid],
2087.                     $this->originalDocumentData[$oid],
2088.                     $this->parentAssociations[$oid],
2089.                     $this->documentUpserts[$oid],
2090.                     $this->hasScheduledCollections[$oid],
2091.                     $this->embeddedDocumentsRegistry[$oid],
2092.                 );
2093.                 break;
2094.             case self::STATE_NEW:
2095.             case self::STATE_DETACHED:
2096.                 return;
2097.         }
2099.         $this->cascadeDetach($document, $visited);
2100.     }
2102.     /**
2103.      * Refreshes the state of the given document from the database, overwriting
2104.      * any local, unpersisted changes.
2105.      *
2106.      * @internal
2107.      *
2108.      * @throws InvalidArgumentException If the document is not MANAGED.
2109.      */
2110.     public function refresh(object $document): void
2111.     {
2112.         $visited = [];
2113.         $this->doRefresh($document, $visited);
2114.     }
2116.     /**
2117.      * Executes a refresh operation on a document.
2118.      *
2119.      * @param array<string, object> $visited
2120.      *
2121.      * @throws InvalidArgumentException If the document is not MANAGED.
2122.      */
2123.     private function doRefresh(object $document, array &$visited): void
2124.     {
2125.         $oid = spl_object_hash($document);
2126.         if (isset($visited[$oid])) {
2127.             return; // Prevent infinite recursion
2128.         }
2130.         $visited[$oid] = $document; // mark visited
2132.         $class = $this->dm->getClassMetadata(get_class($document));
2134.         if (! $class->isEmbeddedDocument) {
2135.             if ($this->getDocumentState($document) !== self::STATE_MANAGED) {
2136.                 throw new InvalidArgumentException('Document is not MANAGED.');
2137.             }
2139.             $this->getDocumentPersister($class->name)->refresh($document);
2140.         }
2142.         $this->cascadeRefresh($document, $visited);
2143.     }
2145.     /**
2146.      * Cascades a refresh operation to associated documents.
2147.      *
2148.      * @param array<string, object> $visited
2149.      */
2150.     private function cascadeRefresh(object $document, array &$visited): void
2151.     {
2152.         $class = $this->dm->getClassMetadata(get_class($document));
2154.         $associationMappings = array_filter(
2155.             $class->associationMappings,
2156.             static fn ($assoc) => $assoc['isCascadeRefresh']
2157.         );
2159.         foreach ($associationMappings as $mapping) {
2160.             $relatedDocuments = $class->reflFields[$mapping['fieldName']]->getValue($document);
2161.             if ($relatedDocuments instanceof Collection || is_array($relatedDocuments)) {
2162.                 if ($relatedDocuments instanceof PersistentCollectionInterface) {
2163.                     // Unwrap so that foreach() does not initialize
2164.                     $relatedDocuments = $relatedDocuments->unwrap();
2165.                 }
2167.                 foreach ($relatedDocuments as $relatedDocument) {
2168.                     $this->doRefresh($relatedDocument, $visited);
2169.                 }
2170.             } elseif ($relatedDocuments !== null) {
2171.                 $this->doRefresh($relatedDocuments, $visited);
2172.             }
2173.         }
2174.     }
2176.     /**
2177.      * Cascades a detach operation to associated documents.
2178.      *
2179.      * @param array<string, object> $visited
2180.      */
2181.     private function cascadeDetach(object $document, array &$visited): void
2182.     {
2183.         $class = $this->dm->getClassMetadata(get_class($document));
2184.         foreach ($class->fieldMappings as $mapping) {
2185.             if (! $mapping['isCascadeDetach']) {
2186.                 continue;
2187.             }
2189.             $relatedDocuments = $class->reflFields[$mapping['fieldName']]->getValue($document);
2190.             if ($relatedDocuments instanceof Collection || is_array($relatedDocuments)) {
2191.                 if ($relatedDocuments instanceof PersistentCollectionInterface) {
2192.                     // Unwrap so that foreach() does not initialize
2193.                     $relatedDocuments = $relatedDocuments->unwrap();
2194.                 }
2196.                 foreach ($relatedDocuments as $relatedDocument) {
2197.                     $this->doDetach($relatedDocument, $visited);
2198.                 }
2199.             } elseif ($relatedDocuments !== null) {
2200.                 $this->doDetach($relatedDocuments, $visited);
2201.             }
2202.         }
2203.     }
2205.     /**
2206.      * Cascades a merge operation to associated documents.
2207.      *
2208.      * @param array<string, object> $visited
2209.      */
2210.     private function cascadeMerge(object $document, object $managedCopy, array &$visited): void
2211.     {
2212.         $class = $this->dm->getClassMetadata(get_class($document));
2214.         $associationMappings = array_filter(
2215.             $class->associationMappings,
2216.             static fn ($assoc) => $assoc['isCascadeMerge']
2217.         );
2219.         foreach ($associationMappings as $assoc) {
2220.             $relatedDocuments = $class->reflFields[$assoc['fieldName']]->getValue($document);
2222.             if ($relatedDocuments instanceof Collection || is_array($relatedDocuments)) {
2223.                 if ($relatedDocuments === $class->reflFields[$assoc['fieldName']]->getValue($managedCopy)) {
2224.                     // Collections are the same, so there is nothing to do
2225.                     continue;
2226.                 }
2228.                 foreach ($relatedDocuments as $relatedDocument) {
2229.                     $this->doMerge($relatedDocument, $visited, $managedCopy, $assoc);
2230.                 }
2231.             } elseif ($relatedDocuments !== null) {
2232.                 $this->doMerge($relatedDocuments, $visited, $managedCopy, $assoc);
2233.             }
2234.         }
2235.     }
2237.     /**
2238.      * Cascades the save operation to associated documents.
2239.      *
2240.      * @param array<string, object> $visited
2241.      */
2242.     private function cascadePersist(object $document, array &$visited): void
2243.     {
2244.         $class = $this->dm->getClassMetadata(get_class($document));
2246.         $associationMappings = array_filter(
2247.             $class->associationMappings,
2248.             static fn ($assoc) => $assoc['isCascadePersist']
2249.         );
2251.         foreach ($associationMappings as $fieldName => $mapping) {
2252.             $relatedDocuments = $class->reflFields[$fieldName]->getValue($document);
2254.             if ($relatedDocuments instanceof Collection || is_array($relatedDocuments)) {
2255.                 if ($relatedDocuments instanceof PersistentCollectionInterface) {
2256.                     if ($relatedDocuments->getOwner() !== $document) {
2257.                         $relatedDocuments = $this->fixPersistentCollectionOwnership($relatedDocuments, $document, $class, $mapping['fieldName']);
2258.                     }
2260.                     // Unwrap so that foreach() does not initialize
2261.                     $relatedDocuments = $relatedDocuments->unwrap();
2262.                 }
2264.                 $count = 0;
2265.                 foreach ($relatedDocuments as $relatedKey => $relatedDocument) {
2266.                     if (! empty($mapping['embedded'])) {
2267.                         [, $knownParent] = $this->getParentAssociation($relatedDocument);
2268.                         if ($knownParent && $knownParent !== $document) {
2269.                             $relatedDocument               = clone $relatedDocument;
2270.                             $relatedDocuments[$relatedKey] = $relatedDocument;
2271.                         }
2273.                         $pathKey = CollectionHelper::isList($mapping['strategy']) ? $count++ : $relatedKey;
2274.                         $this->setParentAssociation($relatedDocument, $mapping, $document, $mapping['fieldName'] . '.' . $pathKey);
2275.                     }
2277.                     $this->doPersist($relatedDocument, $visited);
2278.                 }
2279.             } elseif ($relatedDocuments !== null) {
2280.                 if (! empty($mapping['embedded'])) {
2281.                     [, $knownParent] = $this->getParentAssociation($relatedDocuments);
2282.                     if ($knownParent && $knownParent !== $document) {
2283.                         $relatedDocuments = clone $relatedDocuments;
2284.                         $class->setFieldValue($document, $mapping['fieldName'], $relatedDocuments);
2285.                     }
2287.                     $this->setParentAssociation($relatedDocuments, $mapping, $document, $mapping['fieldName']);
2288.                 }
2290.                 $this->doPersist($relatedDocuments, $visited);
2291.             }
2292.         }
2293.     }
2295.     /**
2296.      * Cascades the delete operation to associated documents.
2297.      *
2298.      * @param array<string, object> $visited
2299.      */
2300.     private function cascadeRemove(object $document, array &$visited): void
2301.     {
2302.         $class = $this->dm->getClassMetadata(get_class($document));
2303.         foreach ($class->fieldMappings as $mapping) {
2304.             if (! $mapping['isCascadeRemove'] && ( ! isset($mapping['orphanRemoval']) || ! $mapping['orphanRemoval'])) {
2305.                 continue;
2306.             }
2308.             if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
2309.                 $document->initializeProxy();
2310.             }
2312.             $relatedDocuments = $class->reflFields[$mapping['fieldName']]->getValue($document);
2313.             if ($relatedDocuments instanceof Collection || is_array($relatedDocuments)) {
2314.                 // If its a PersistentCollection initialization is intended! No unwrap!
2315.                 foreach ($relatedDocuments as $relatedDocument) {
2316.                     $this->doRemove($relatedDocument, $visited);
2317.                 }
2318.             } elseif ($relatedDocuments !== null) {
2319.                 $this->doRemove($relatedDocuments, $visited);
2320.             }
2321.         }
2322.     }
2324.     /**
2325.      * Acquire a lock on the given document.
2326.      *
2327.      * @internal
2328.      *
2329.      * @throws LockException
2330.      * @throws InvalidArgumentException
2331.      */
2332.     public function lock(object $document, int $lockMode, ?int $lockVersion = null): void
2333.     {
2334.         if ($this->getDocumentState($document) !== self::STATE_MANAGED) {
2335.             throw new InvalidArgumentException('Document is not MANAGED.');
2336.         }
2338.         $documentName = get_class($document);
2339.         $class        = $this->dm->getClassMetadata($documentName);
2341.         if ($lockMode === LockMode::OPTIMISTIC) {
2342.             if (! $class->isVersioned) {
2343.                 throw LockException::notVersioned($documentName);
2344.             }
2346.             if ($lockVersion !== null) {
2347.                 $documentVersion = $class->reflFields[$class->versionField]->getValue($document);
2348.                 if ($documentVersion !== $lockVersion) {
2349.                     throw LockException::lockFailedVersionMissmatch($document, $lockVersion, $documentVersion);
2350.                 }
2351.             }
2352.         } elseif (in_array($lockMode, [LockMode::PESSIMISTIC_READ, LockMode::PESSIMISTIC_WRITE])) {
2353.             $this->getDocumentPersister($class->name)->lock($document, $lockMode);
2354.         }
2355.     }
2357.     /**
2358.      * Releases a lock on the given document.
2359.      *
2360.      * @internal
2361.      *
2362.      * @throws InvalidArgumentException
2363.      */
2364.     public function unlock(object $document): void
2365.     {
2366.         if ($this->getDocumentState($document) !== self::STATE_MANAGED) {
2367.             throw new InvalidArgumentException('Document is not MANAGED.');
2368.         }
2370.         $documentName = get_class($document);
2371.         $this->getDocumentPersister($documentName)->unlock($document);
2372.     }
2374.     /**
2375.      * Clears the UnitOfWork.
2376.      *
2377.      * @internal
2378.      */
2379.     public function clear(?string $documentName = null): void
2380.     {
2381.         if ($documentName === null) {
2382.             $this->identityMap                 =
2383.             $this->documentIdentifiers         =
2384.             $this->originalDocumentData        =
2385.             $this->documentChangeSets          =
2386.             $this->documentStates              =
2387.             $this->scheduledForSynchronization =
2388.             $this->documentInsertions          =
2389.             $this->documentUpserts             =
2390.             $this->documentUpdates             =
2391.             $this->documentDeletions           =
2392.             $this->collectionUpdates           =
2393.             $this->collectionDeletions         =
2394.             $this->parentAssociations          =
2395.             $this->embeddedDocumentsRegistry   =
2396.             $this->orphanRemovals              =
2397.             $this->hasScheduledCollections     = [];
2398.         } else {
2399.             $visited = [];
2400.             foreach ($this->identityMap as $className => $documents) {
2401.                 if ($className !== $documentName) {
2402.                     continue;
2403.                 }
2405.                 foreach ($documents as $document) {
2406.                     $this->doDetach($document, $visited);
2407.                 }
2408.             }
2409.         }
2411.         $this->evm->dispatchEvent(Events::onClear, new Event\OnClearEventArgs($this->dm, $documentName));
2412.     }
2414.     /**
2415.      * Schedules an embedded document for removal. The remove() operation will be
2416.      * invoked on that document at the beginning of the next commit of this
2417.      * UnitOfWork.
2418.      *
2419.      * @internal
2420.      */
2421.     public function scheduleOrphanRemoval(object $document): void
2422.     {
2423.         $this->orphanRemovals[spl_object_hash($document)] = $document;
2424.     }
2426.     /**
2427.      * Unschedules an embedded or referenced object for removal.
2428.      *
2429.      * @internal
2430.      */
2431.     public function unscheduleOrphanRemoval(object $document): void
2432.     {
2433.         $oid = spl_object_hash($document);
2434.         unset($this->orphanRemovals[$oid]);
2435.     }
2437.     /**
2438.      * Fixes PersistentCollection state if it wasn't used exactly as we had in mind:
2439.      *  1) sets owner if it was cloned
2440.      *  2) clones collection, sets owner, updates document's property and, if necessary, updates originalData
2441.      *  3) NOP if state is OK
2442.      * Returned collection should be used from now on (only important with 2nd point)
2443.      *
2444.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2445.      * @psalm-param T $document
2446.      * @psalm-param ClassMetadata<T> $class
2447.      *
2448.      * @psalm-return PersistentCollectionInterface<array-key, object>
2449.      *
2450.      * @template T of object
2451.      */
2452.     private function fixPersistentCollectionOwnership(PersistentCollectionInterface $coll, object $document, ClassMetadata $class, string $propName): PersistentCollectionInterface
2453.     {
2454.         $owner = $coll->getOwner();
2455.         if ($owner === null) { // cloned
2456.             $coll->setOwner($document, $class->fieldMappings[$propName]);
2457.         } elseif ($owner !== $document) { // no clone, we have to fix
2458.             if (! $coll->isInitialized()) {
2459.                 $coll->initialize(); // we have to do this otherwise the cols share state
2460.             }
2462.             $newValue = clone $coll;
2463.             $newValue->setOwner($document, $class->fieldMappings[$propName]);
2464.             $class->reflFields[$propName]->setValue($document, $newValue);
2465.             if ($this->isScheduledForUpdate($document)) {
2466.                 // @todo following line should be superfluous once collections are stored in change sets
2467.                 $this->setOriginalDocumentProperty(spl_object_hash($document), $propName, $newValue);
2468.             }
2470.             return $newValue;
2471.         }
2473.         return $coll;
2474.     }
2476.     /**
2477.      * Schedules a complete collection for removal when this UnitOfWork commits.
2478.      *
2479.      * @internal
2480.      *
2481.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2482.      */
2483.     public function scheduleCollectionDeletion(PersistentCollectionInterface $coll): void
2484.     {
2485.         $oid = spl_object_hash($coll);
2486.         unset($this->collectionUpdates[$oid]);
2487.         if (isset($this->collectionDeletions[$oid])) {
2488.             return;
2489.         }
2491.         $this->collectionDeletions[$oid] = $coll;
2492.         $this->scheduleCollectionOwner($coll);
2493.     }
2495.     /**
2496.      * Checks whether a PersistentCollection is scheduled for deletion.
2497.      *
2498.      * @internal
2499.      *
2500.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2501.      */
2502.     public function isCollectionScheduledForDeletion(PersistentCollectionInterface $coll): bool
2503.     {
2504.         return isset($this->collectionDeletions[spl_object_hash($coll)]);
2505.     }
2507.     /**
2508.      * Unschedules a collection from being deleted when this UnitOfWork commits.
2509.      *
2510.      * @internal
2511.      *
2512.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2513.      */
2514.     public function unscheduleCollectionDeletion(PersistentCollectionInterface $coll): void
2515.     {
2516.         if ($coll->getOwner() === null) {
2517.             return;
2518.         }
2520.         $oid = spl_object_hash($coll);
2521.         if (! isset($this->collectionDeletions[$oid])) {
2522.             return;
2523.         }
2525.         $topmostOwner = $this->getOwningDocument($coll->getOwner());
2526.         unset($this->collectionDeletions[$oid]);
2527.         unset($this->hasScheduledCollections[spl_object_hash($topmostOwner)][$oid]);
2528.     }
2530.     /**
2531.      * Schedules a collection for update when this UnitOfWork commits.
2532.      *
2533.      * @internal
2534.      *
2535.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2536.      */
2537.     public function scheduleCollectionUpdate(PersistentCollectionInterface $coll): void
2538.     {
2539.         $mapping = $coll->getMapping();
2540.         if (CollectionHelper::usesSet($mapping['strategy'])) {
2541.             /* There is no need to $unset collection if it will be $set later
2542.              * This is NOP if collection is not scheduled for deletion
2543.              */
2544.             $this->unscheduleCollectionDeletion($coll);
2545.         }
2547.         $oid = spl_object_hash($coll);
2548.         if (isset($this->collectionUpdates[$oid])) {
2549.             return;
2550.         }
2552.         $this->collectionUpdates[$oid] = $coll;
2553.         $this->scheduleCollectionOwner($coll);
2554.     }
2556.     /**
2557.      * Unschedules a collection from being updated when this UnitOfWork commits.
2558.      *
2559.      * @internal
2560.      *
2561.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2562.      */
2563.     public function unscheduleCollectionUpdate(PersistentCollectionInterface $coll): void
2564.     {
2565.         if ($coll->getOwner() === null) {
2566.             return;
2567.         }
2569.         $oid = spl_object_hash($coll);
2570.         if (! isset($this->collectionUpdates[$oid])) {
2571.             return;
2572.         }
2574.         $topmostOwner = $this->getOwningDocument($coll->getOwner());
2575.         unset($this->collectionUpdates[$oid]);
2576.         unset($this->hasScheduledCollections[spl_object_hash($topmostOwner)][$oid]);
2577.     }
2579.     /**
2580.      * Checks whether a PersistentCollection is scheduled for update.
2581.      *
2582.      * @internal
2583.      *
2584.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2585.      */
2586.     public function isCollectionScheduledForUpdate(PersistentCollectionInterface $coll): bool
2587.     {
2588.         return isset($this->collectionUpdates[spl_object_hash($coll)]);
2589.     }
2591.     /**
2592.      * Gets PersistentCollections that have been visited during computing change
2593.      * set of $document
2594.      *
2595.      * @internal
2596.      *
2597.      * @return PersistentCollectionInterface[]
2598.      * @psalm-return array<PersistentCollectionInterface<array-key, object>>
2599.      */
2600.     public function getVisitedCollections(object $document): array
2601.     {
2602.         $oid = spl_object_hash($document);
2604.         return $this->visitedCollections[$oid] ?? [];
2605.     }
2607.     /**
2608.      * Gets PersistentCollections that are scheduled to update and related to $document
2609.      *
2610.      * @internal
2611.      *
2612.      * @return PersistentCollectionInterface[]
2613.      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
2614.      */
2615.     public function getScheduledCollections(object $document): array
2616.     {
2617.         $oid = spl_object_hash($document);
2619.         return $this->hasScheduledCollections[$oid] ?? [];
2620.     }
2622.     /**
2623.      * Checks whether the document is related to a PersistentCollection
2624.      * scheduled for update or deletion.
2625.      *
2626.      * @internal
2627.      */
2628.     public function hasScheduledCollections(object $document): bool
2629.     {
2630.         return isset($this->hasScheduledCollections[spl_object_hash($document)]);
2631.     }
2633.     /**
2634.      * Marks the PersistentCollection's top-level owner as having a relation to
2635.      * a collection scheduled for update or deletion.
2636.      *
2637.      * If the owner is not scheduled for any lifecycle action, it will be
2638.      * scheduled for update to ensure that versioning takes place if necessary.
2639.      *
2640.      * If the collection is nested within atomic collection, it is immediately
2641.      * unscheduled and atomic one is scheduled for update instead. This makes
2642.      * calculating update data way easier.
2643.      *
2644.      * @psalm-param PersistentCollectionInterface<array-key, object> $coll
2645.      */
2646.     private function scheduleCollectionOwner(PersistentCollectionInterface $coll): void
2647.     {
2648.         if ($coll->getOwner() === null) {
2649.             return;
2650.         }
2652.         $document                                                                          = $this->getOwningDocument($coll->getOwner());
2653.         $this->hasScheduledCollections[spl_object_hash($document)][spl_object_hash($coll)] = $coll;
2655.         if ($document !== $coll->getOwner()) {
2656.             $parent  = $coll->getOwner();
2657.             $mapping = [];
2658.             while (($parentAssoc = $this->getParentAssociation($parent)) !== null) {
2659.                 [$mapping, $parent] = $parentAssoc;
2660.             }
2662.             if (CollectionHelper::isAtomic($mapping['strategy'])) {
2663.                 $class            = $this->dm->getClassMetadata(get_class($document));
2664.                 $atomicCollection = $class->getFieldValue($document, $mapping['fieldName']);
2665.                 $this->scheduleCollectionUpdate($atomicCollection);
2666.                 $this->unscheduleCollectionDeletion($coll);
2667.                 $this->unscheduleCollectionUpdate($coll);
2668.             }
2669.         }
2671.         if ($this->isDocumentScheduled($document)) {
2672.             return;
2673.         }
2675.         $this->scheduleForUpdate($document);
2676.     }
2678.     /**
2679.      * Get the top-most owning document of a given document
2680.      *
2681.      * If a top-level document is provided, that same document will be returned.
2682.      * For an embedded document, we will walk through parent associations until
2683.      * we find a top-level document.
2684.      *
2685.      * @throws UnexpectedValueException When a top-level document could not be found.
2686.      */
2687.     public function getOwningDocument(object $document): object
2688.     {
2689.         $class = $this->dm->getClassMetadata(get_class($document));
2690.         while ($class->isEmbeddedDocument) {
2691.             $parentAssociation = $this->getParentAssociation($document);
2693.             if (! $parentAssociation) {
2694.                 throw new UnexpectedValueException('Could not determine parent association for ' . get_class($document));
2695.             }
2697.             [, $document] = $parentAssociation;
2698.             $class        = $this->dm->getClassMetadata(get_class($document));
2699.         }
2701.         return $document;
2702.     }
2704.     /**
2705.      * Gets the class name for an association (embed or reference) with respect
2706.      * to any discriminator value.
2707.      *
2708.      * @internal
2709.      *
2710.      * @param FieldMapping              $mapping
2711.      * @param array<string, mixed>|null $data
2712.      *
2713.      * @psalm-return class-string
2714.      */
2715.     public function getClassNameForAssociation(array $mapping, $data): string
2716.     {
2717.         $discriminatorField = $mapping['discriminatorField'] ?? null;
2719.         $discriminatorValue = null;
2720.         if (isset($discriminatorField, $data[$discriminatorField])) {
2721.             $discriminatorValue = $data[$discriminatorField];
2722.         } elseif (isset($mapping['defaultDiscriminatorValue'])) {
2723.             $discriminatorValue = $mapping['defaultDiscriminatorValue'];
2724.         }
2726.         if ($discriminatorValue !== null) {
2727.             return $mapping['discriminatorMap'][$discriminatorValue]
2728.                 ?? (string) $discriminatorValue;
2729.         }
2731.         $class = $this->dm->getClassMetadata($mapping['targetDocument']);
2733.         if (isset($class->discriminatorField, $data[$class->discriminatorField])) {
2734.             $discriminatorValue = $data[$class->discriminatorField];
2735.         } elseif ($class->defaultDiscriminatorValue !== null) {
2736.             $discriminatorValue = $class->defaultDiscriminatorValue;
2737.         }
2739.         if ($discriminatorValue !== null) {
2740.             return $class->discriminatorMap[$discriminatorValue] ?? $discriminatorValue;
2741.         }
2743.         return $mapping['targetDocument'];
2744.     }
2746.     /**
2747.      * Creates a document. Used for reconstitution of documents during hydration.
2748.      *
2749.      * @psalm-param class-string<T> $className
2750.      * @psalm-param array<string, mixed> $data
2751.      * @psalm-param T|null $document
2752.      * @psalm-param Hints $hints
2753.      *
2754.      * @psalm-return T
2755.      *
2756.      * @template T of object
2757.      */
2758.     public function getOrCreateDocument(string $className, array $data, array &$hints = [], ?object $document = null): object
2759.     {
2760.         $class = $this->dm->getClassMetadata($className);
2762.         // @TODO figure out how to remove this
2763.         $discriminatorValue = null;
2764.         if (isset($class->discriminatorField, $data[$class->discriminatorField])) {
2765.             $discriminatorValue = $data[$class->discriminatorField];
2766.         } elseif (isset($class->defaultDiscriminatorValue)) {
2767.             $discriminatorValue = $class->defaultDiscriminatorValue;
2768.         }
2770.         if ($discriminatorValue !== null) {
2771.             /** @psalm-var class-string<T> $className */
2772.             $className =  $class->discriminatorMap[$discriminatorValue] ?? $discriminatorValue;
2774.             $class = $this->dm->getClassMetadata($className);
2776.             unset($data[$class->discriminatorField]);
2777.         }
2779.         if (! empty($hints[Query::HINT_READ_ONLY])) {
2780.             /** @psalm-var T $document */
2781.             $document = $class->newInstance();
2782.             $this->hydratorFactory->hydrate($document, $data, $hints);
2784.             return $document;
2785.         }
2787.         $isManagedObject = false;
2788.         $serializedId    = null;
2789.         $id              = null;
2790.         if (! $class->isQueryResultDocument) {
2791.             $id              = $class->getDatabaseIdentifierValue($data['_id']);
2792.             $serializedId    = serialize($id);
2793.             $isManagedObject = isset($this->identityMap[$class->name][$serializedId]);
2794.         }
2796.         $oid = null;
2797.         if ($isManagedObject) {
2798.             /** @psalm-var T $document */
2799.             $document = $this->identityMap[$class->name][$serializedId];
2800.             $oid      = spl_object_hash($document);
2801.             if ($document instanceof GhostObjectInterface && ! $document->isProxyInitialized()) {
2802.                 $document->setProxyInitializer(null);
2803.                 $overrideLocalValues = true;
2804.                 if ($document instanceof NotifyPropertyChanged) {
2805.                     $document->addPropertyChangedListener($this);
2806.                 }
2807.             } else {
2808.                 $overrideLocalValues = ! empty($hints[Query::HINT_REFRESH]);
2809.             }
2811.             if ($overrideLocalValues) {
2812.                 $data                             = $this->hydratorFactory->hydrate($document, $data, $hints);
2813.                 $this->originalDocumentData[$oid] = $data;
2814.             }
2815.         } else {
2816.             if ($document === null) {
2817.                 /** @psalm-var T $document */
2818.                 $document = $class->newInstance();
2819.             }
2821.             if (! $class->isQueryResultDocument) {
2822.                 $this->registerManaged($document, $id, $data);
2823.                 $oid                                            = spl_object_hash($document);
2824.                 $this->documentStates[$oid]                     = self::STATE_MANAGED;
2825.                 $this->identityMap[$class->name][$serializedId] = $document;
2826.             }
2828.             $data = $this->hydratorFactory->hydrate($document, $data, $hints);
2830.             if (! $class->isQueryResultDocument && ! $class->isView()) {
2831.                 $this->originalDocumentData[$oid] = $data;
2832.             }
2833.         }
2835.         return $document;
2836.     }
2838.     /**
2839.      * Initializes (loads) an uninitialized persistent collection of a document.
2840.      *
2841.      * @internal
2842.      *
2843.      * @psalm-param PersistentCollectionInterface<array-key, object> $collection
2844.      */
2845.     public function loadCollection(PersistentCollectionInterface $collection): void
2846.     {
2847.         if ($collection->getOwner() === null) {
2848.             throw PersistentCollectionException::ownerRequiredToLoadCollection();
2849.         }
2851.         $this->getDocumentPersister(get_class($collection->getOwner()))->loadCollection($collection);
2852.         $this->lifecycleEventManager->postCollectionLoad($collection);
2853.     }
2855.     /**
2856.      * Gets the identity map of the UnitOfWork.
2857.      *
2858.      * @internal
2859.      *
2860.      * @psalm-return array<class-string, array<string, object>>
2861.      */
2862.     public function getIdentityMap(): array
2863.     {
2864.         return $this->identityMap;
2865.     }
2867.     /**
2868.      * Gets the original data of a document. The original data is the data that was
2869.      * present at the time the document was reconstituted from the database.
2870.      *
2871.      * @return array<string, mixed>
2872.      */
2873.     public function getOriginalDocumentData(object $document): array
2874.     {
2875.         $oid = spl_object_hash($document);
2877.         return $this->originalDocumentData[$oid] ?? [];
2878.     }
2880.     /**
2881.      * @internal
2882.      *
2883.      * @param array<string, mixed> $data
2884.      */
2885.     public function setOriginalDocumentData(object $document, array $data): void
2886.     {
2887.         $oid                              = spl_object_hash($document);
2888.         $this->originalDocumentData[$oid] = $data;
2889.         unset($this->documentChangeSets[$oid]);
2890.     }
2892.     /**
2893.      * Sets a property value of the original data array of a document.
2894.      *
2895.      * @internal
2896.      *
2897.      * @param mixed $value
2898.      */
2899.     public function setOriginalDocumentProperty(string $oid, string $property, $value): void
2900.     {
2901.         $this->originalDocumentData[$oid][$property] = $value;
2902.     }
2904.     /**
2905.      * Gets the identifier of a document.
2906.      *
2907.      * @return mixed The identifier value
2908.      */
2909.     public function getDocumentIdentifier(object $document)
2910.     {
2911.         return $this->documentIdentifiers[spl_object_hash($document)] ?? null;
2912.     }
2914.     /**
2915.      * Checks whether the UnitOfWork has any pending insertions.
2916.      *
2917.      * @internal
2918.      *
2919.      * @return bool TRUE if this UnitOfWork has pending insertions, FALSE otherwise.
2920.      */
2921.     public function hasPendingInsertions(): bool
2922.     {
2923.         return ! empty($this->documentInsertions);
2924.     }
2926.     /**
2927.      * Calculates the size of the UnitOfWork. The size of the UnitOfWork is the
2928.      * number of documents in the identity map.
2929.      *
2930.      * @internal
2931.      */
2932.     public function size(): int
2933.     {
2934.         $count = 0;
2935.         foreach ($this->identityMap as $documentSet) {
2936.             $count += count($documentSet);
2937.         }
2939.         return $count;
2940.     }
2942.     /**
2943.      * Registers a document as managed.
2944.      *
2945.      * TODO: This method assumes that $id is a valid PHP identifier for the
2946.      * document class. If the class expects its database identifier to be an
2947.      * ObjectId, and an incompatible $id is registered (e.g. an integer), the
2948.      * document identifiers map will become inconsistent with the identity map.
2949.      * In the future, we may want to round-trip $id through a PHP and database
2950.      * conversion and throw an exception if it's inconsistent.
2951.      *
2952.      * @internal
2953.      *
2954.      * @param mixed                $id   The identifier values.
2955.      * @param array<string, mixed> $data
2956.      */
2957.     public function registerManaged(object $document, $id, array $data): void
2958.     {
2959.         $oid   = spl_object_hash($document);
2960.         $class = $this->dm->getClassMetadata(get_class($document));
2962.         if (! $class->identifier || $id === null) {
2963.             $this->documentIdentifiers[$oid] = $oid;
2964.         } else {
2965.             $this->documentIdentifiers[$oid] = $class->getPHPIdentifierValue($id);
2966.         }
2968.         $this->documentStates[$oid]       = self::STATE_MANAGED;
2969.         $this->originalDocumentData[$oid] = $data;
2970.         $this->addToIdentityMap($document);
2971.     }
2973.     /**
2974.      * Clears the property changeset of the document with the given OID.
2975.      *
2976.      * @internal
2977.      */
2978.     public function clearDocumentChangeSet(string $oid): void
2979.     {
2980.         $this->documentChangeSets[$oid] = [];
2981.     }
2983.     /* PropertyChangedListener implementation */
2985.     /**
2986.      * Notifies this UnitOfWork of a property change in a document.
2987.      *
2988.      * @param object $sender       The document that owns the property.
2989.      * @param string $propertyName The name of the property that changed.
2990.      * @param mixed  $oldValue     The old value of the property.
2991.      * @param mixed  $newValue     The new value of the property.
2992.      */
2993.     public function propertyChanged($sender, $propertyName, $oldValue, $newValue)
2994.     {
2995.         $oid   = spl_object_hash($sender);
2996.         $class = $this->dm->getClassMetadata(get_class($sender));
2998.         if (! isset($class->fieldMappings[$propertyName])) {
2999.             return; // ignore non-persistent fields
3000.         }
3002.         // Update changeset and mark document for synchronization
3003.         $this->documentChangeSets[$oid][$propertyName] = [$oldValue, $newValue];
3004.         if (isset($this->scheduledForSynchronization[$class->name][$oid])) {
3005.             return;
3006.         }
3008.         $this->scheduleForSynchronization($sender);
3009.     }
3011.     /**
3012.      * Gets the currently scheduled document insertions in this UnitOfWork.
3013.      *
3014.      * @psalm-return array<string, object>
3015.      */
3016.     public function getScheduledDocumentInsertions(): array
3017.     {
3018.         return $this->documentInsertions;
3019.     }
3021.     /**
3022.      * Gets the currently scheduled document upserts in this UnitOfWork.
3023.      *
3024.      * @psalm-return array<string, object>
3025.      */
3026.     public function getScheduledDocumentUpserts(): array
3027.     {
3028.         return $this->documentUpserts;
3029.     }
3031.     /**
3032.      * Gets the currently scheduled document updates in this UnitOfWork.
3033.      *
3034.      * @psalm-return array<string, object>
3035.      */
3036.     public function getScheduledDocumentUpdates(): array
3037.     {
3038.         return $this->documentUpdates;
3039.     }
3041.     /**
3042.      * Gets the currently scheduled document deletions in this UnitOfWork.
3043.      *
3044.      * @psalm-return array<string, object>
3045.      */
3046.     public function getScheduledDocumentDeletions(): array
3047.     {
3048.         return $this->documentDeletions;
3049.     }
3051.     /**
3052.      * Get the currently scheduled complete collection deletions
3053.      *
3054.      * @internal
3055.      *
3056.      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
3057.      */
3058.     public function getScheduledCollectionDeletions(): array
3059.     {
3060.         return $this->collectionDeletions;
3061.     }
3063.     /**
3064.      * Gets the currently scheduled collection inserts, updates and deletes.
3065.      *
3066.      * @internal
3067.      *
3068.      * @psalm-return array<string, PersistentCollectionInterface<array-key, object>>
3069.      */
3070.     public function getScheduledCollectionUpdates(): array
3071.     {
3072.         return $this->collectionUpdates;
3073.     }
3075.     /**
3076.      * Helper method to initialize a lazy loading proxy or persistent collection.
3077.      *
3078.      * @internal
3079.      */
3080.     public function initializeObject(object $obj): void
3081.     {
3082.         if ($obj instanceof GhostObjectInterface) {
3083.             $obj->initializeProxy();
3084.         } elseif ($obj instanceof PersistentCollectionInterface) {
3085.             $obj->initialize();
3086.         }
3087.     }
3089.     private function objToStr(object $obj): string
3090.     {
3091.         return method_exists($obj, '__toString') ? (string) $obj : get_class($obj) . '@' . spl_object_hash($obj);
3092.     }
3093. }