vendor/doctrine/orm/lib/Doctrine/ORM/PersistentCollection.php line 53

Open in your IDE?
  1. <?php
  2. /*
  3.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  4.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  5.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  6.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  7.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  8.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  9.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14.  *
  15.  * This software consists of voluntary contributions made by many individuals
  16.  * and is licensed under the MIT license. For more information, see
  17.  * <http://www.doctrine-project.org>.
  18.  */
  19. namespace Doctrine\ORM;
  20. use Doctrine\Common\Collections\AbstractLazyCollection;
  21. use Doctrine\Common\Collections\ArrayCollection;
  22. use Doctrine\Common\Collections\Collection;
  23. use Doctrine\Common\Collections\Criteria;
  24. use Doctrine\Common\Collections\Selectable;
  25. use Doctrine\ORM\Mapping\ClassMetadata;
  26. use RuntimeException;
  27. use function array_combine;
  28. use function array_diff_key;
  29. use function array_map;
  30. use function array_udiff_assoc;
  31. use function array_walk;
  32. use function get_class;
  33. use function is_object;
  34. use function spl_object_hash;
  35. /**
  36.  * A PersistentCollection represents a collection of elements that have persistent state.
  37.  *
  38.  * Collections of entities represent only the associations (links) to those entities.
  39.  * That means, if the collection is part of a many-many mapping and you remove
  40.  * entities from the collection, only the links in the relation table are removed (on flush).
  41.  * Similarly, if you remove entities from a collection that is part of a one-many
  42.  * mapping this will only result in the nulling out of the foreign keys on flush.
  43.  *
  44.  * @psalm-template TKey of array-key
  45.  * @psalm-template T
  46.  * @template-implements Collection<TKey,T>
  47.  */
  48. final class PersistentCollection extends AbstractLazyCollection implements Selectable
  49. {
  50.     /**
  51.      * A snapshot of the collection at the moment it was fetched from the database.
  52.      * This is used to create a diff of the collection at commit time.
  53.      *
  54.      * @psalm-var array<string|int, mixed>
  55.      */
  56.     private $snapshot = [];
  57.     /**
  58.      * The entity that owns this collection.
  59.      *
  60.      * @var object|null
  61.      */
  62.     private $owner;
  63.     /**
  64.      * The association mapping the collection belongs to.
  65.      * This is currently either a OneToManyMapping or a ManyToManyMapping.
  66.      *
  67.      * @psalm-var array<string, mixed>|null
  68.      */
  69.     private $association;
  70.     /**
  71.      * The EntityManager that manages the persistence of the collection.
  72.      *
  73.      * @var EntityManagerInterface
  74.      */
  75.     private $em;
  76.     /**
  77.      * The name of the field on the target entities that points to the owner
  78.      * of the collection. This is only set if the association is bi-directional.
  79.      *
  80.      * @var string
  81.      */
  82.     private $backRefFieldName;
  83.     /**
  84.      * The class descriptor of the collection's entity type.
  85.      *
  86.      * @var ClassMetadata
  87.      */
  88.     private $typeClass;
  89.     /**
  90.      * Whether the collection is dirty and needs to be synchronized with the database
  91.      * when the UnitOfWork that manages its persistent state commits.
  92.      *
  93.      * @var bool
  94.      */
  95.     private $isDirty false;
  96.     /**
  97.      * Creates a new persistent collection.
  98.      *
  99.      * @param EntityManagerInterface $em    The EntityManager the collection will be associated with.
  100.      * @param ClassMetadata          $class The class descriptor of the entity type of this collection.
  101.      * @psalm-param Collection<TKey, T> $collection The collection elements.
  102.      */
  103.     public function __construct(EntityManagerInterface $em$classCollection $collection)
  104.     {
  105.         $this->collection  $collection;
  106.         $this->em          $em;
  107.         $this->typeClass   $class;
  108.         $this->initialized true;
  109.     }
  110.     /**
  111.      * INTERNAL:
  112.      * Sets the collection's owning entity together with the AssociationMapping that
  113.      * describes the association between the owner and the elements of the collection.
  114.      *
  115.      * @param object $entity
  116.      * @psalm-param array<string, mixed> $assoc
  117.      */
  118.     public function setOwner($entity, array $assoc): void
  119.     {
  120.         $this->owner            $entity;
  121.         $this->association      $assoc;
  122.         $this->backRefFieldName $assoc['inversedBy'] ?: $assoc['mappedBy'];
  123.     }
  124.     /**
  125.      * INTERNAL:
  126.      * Gets the collection owner.
  127.      *
  128.      * @return object|null
  129.      */
  130.     public function getOwner()
  131.     {
  132.         return $this->owner;
  133.     }
  134.     /**
  135.      * @return Mapping\ClassMetadata
  136.      */
  137.     public function getTypeClass(): Mapping\ClassMetadataInfo
  138.     {
  139.         return $this->typeClass;
  140.     }
  141.     /**
  142.      * INTERNAL:
  143.      * Adds an element to a collection during hydration. This will automatically
  144.      * complete bidirectional associations in the case of a one-to-many association.
  145.      *
  146.      * @param mixed $element The element to add.
  147.      */
  148.     public function hydrateAdd($element): void
  149.     {
  150.         $this->collection->add($element);
  151.         // If _backRefFieldName is set and its a one-to-many association,
  152.         // we need to set the back reference.
  153.         if ($this->backRefFieldName && $this->association['type'] === ClassMetadata::ONE_TO_MANY) {
  154.             // Set back reference to owner
  155.             $this->typeClass->reflFields[$this->backRefFieldName]->setValue(
  156.                 $element,
  157.                 $this->owner
  158.             );
  159.             $this->em->getUnitOfWork()->setOriginalEntityProperty(
  160.                 spl_object_hash($element),
  161.                 $this->backRefFieldName,
  162.                 $this->owner
  163.             );
  164.         }
  165.     }
  166.     /**
  167.      * INTERNAL:
  168.      * Sets a keyed element in the collection during hydration.
  169.      *
  170.      * @param mixed $key     The key to set.
  171.      * @param mixed $element The element to set.
  172.      */
  173.     public function hydrateSet($key$element): void
  174.     {
  175.         $this->collection->set($key$element);
  176.         // If _backRefFieldName is set, then the association is bidirectional
  177.         // and we need to set the back reference.
  178.         if ($this->backRefFieldName && $this->association['type'] === ClassMetadata::ONE_TO_MANY) {
  179.             // Set back reference to owner
  180.             $this->typeClass->reflFields[$this->backRefFieldName]->setValue(
  181.                 $element,
  182.                 $this->owner
  183.             );
  184.         }
  185.     }
  186.     /**
  187.      * Initializes the collection by loading its contents from the database
  188.      * if the collection is not yet initialized.
  189.      */
  190.     public function initialize(): void
  191.     {
  192.         if ($this->initialized || ! $this->association) {
  193.             return;
  194.         }
  195.         $this->doInitialize();
  196.         $this->initialized true;
  197.     }
  198.     /**
  199.      * INTERNAL:
  200.      * Tells this collection to take a snapshot of its current state.
  201.      */
  202.     public function takeSnapshot(): void
  203.     {
  204.         $this->snapshot $this->collection->toArray();
  205.         $this->isDirty  false;
  206.     }
  207.     /**
  208.      * INTERNAL:
  209.      * Returns the last snapshot of the elements in the collection.
  210.      *
  211.      * @psalm-return array<string|int, mixed> The last snapshot of the elements.
  212.      */
  213.     public function getSnapshot(): array
  214.     {
  215.         return $this->snapshot;
  216.     }
  217.     /**
  218.      * INTERNAL:
  219.      * getDeleteDiff
  220.      *
  221.      * @return mixed[]
  222.      */
  223.     public function getDeleteDiff(): array
  224.     {
  225.         return array_udiff_assoc(
  226.             $this->snapshot,
  227.             $this->collection->toArray(),
  228.             static function ($a$b): int {
  229.                 return $a === $b 1;
  230.             }
  231.         );
  232.     }
  233.     /**
  234.      * INTERNAL:
  235.      * getInsertDiff
  236.      *
  237.      * @return mixed[]
  238.      */
  239.     public function getInsertDiff(): array
  240.     {
  241.         return array_udiff_assoc(
  242.             $this->collection->toArray(),
  243.             $this->snapshot,
  244.             static function ($a$b): int {
  245.                 return $a === $b 1;
  246.             }
  247.         );
  248.     }
  249.     /**
  250.      * INTERNAL: Gets the association mapping of the collection.
  251.      *
  252.      * @psalm-return array<string, mixed>|null
  253.      */
  254.     public function getMapping(): ?array
  255.     {
  256.         return $this->association;
  257.     }
  258.     /**
  259.      * Marks this collection as changed/dirty.
  260.      */
  261.     private function changed(): void
  262.     {
  263.         if ($this->isDirty) {
  264.             return;
  265.         }
  266.         $this->isDirty true;
  267.         if (
  268.             $this->association !== null &&
  269.             $this->association['isOwningSide'] &&
  270.             $this->association['type'] === ClassMetadata::MANY_TO_MANY &&
  271.             $this->owner &&
  272.             $this->em->getClassMetadata(get_class($this->owner))->isChangeTrackingNotify()
  273.         ) {
  274.             $this->em->getUnitOfWork()->scheduleForDirtyCheck($this->owner);
  275.         }
  276.     }
  277.     /**
  278.      * Gets a boolean flag indicating whether this collection is dirty which means
  279.      * its state needs to be synchronized with the database.
  280.      *
  281.      * @return bool TRUE if the collection is dirty, FALSE otherwise.
  282.      */
  283.     public function isDirty(): bool
  284.     {
  285.         return $this->isDirty;
  286.     }
  287.     /**
  288.      * Sets a boolean flag, indicating whether this collection is dirty.
  289.      *
  290.      * @param bool $dirty Whether the collection should be marked dirty or not.
  291.      */
  292.     public function setDirty($dirty): void
  293.     {
  294.         $this->isDirty $dirty;
  295.     }
  296.     /**
  297.      * Sets the initialized flag of the collection, forcing it into that state.
  298.      *
  299.      * @param bool $bool
  300.      */
  301.     public function setInitialized($bool): void
  302.     {
  303.         $this->initialized $bool;
  304.     }
  305.     /**
  306.      * {@inheritdoc}
  307.      *
  308.      * @return object
  309.      */
  310.     public function remove($key)
  311.     {
  312.         // TODO: If the keys are persistent as well (not yet implemented)
  313.         //       and the collection is not initialized and orphanRemoval is
  314.         //       not used we can issue a straight SQL delete/update on the
  315.         //       association (table). Without initializing the collection.
  316.         $removed parent::remove($key);
  317.         if (! $removed) {
  318.             return $removed;
  319.         }
  320.         $this->changed();
  321.         if (
  322.             $this->association !== null &&
  323.             $this->association['type'] & ClassMetadata::TO_MANY &&
  324.             $this->owner &&
  325.             $this->association['orphanRemoval']
  326.         ) {
  327.             $this->em->getUnitOfWork()->scheduleOrphanRemoval($removed);
  328.         }
  329.         return $removed;
  330.     }
  331.     /**
  332.      * {@inheritdoc}
  333.      */
  334.     public function removeElement($element): bool
  335.     {
  336.         $removed parent::removeElement($element);
  337.         if (! $removed) {
  338.             return $removed;
  339.         }
  340.         $this->changed();
  341.         if (
  342.             $this->association !== null &&
  343.             $this->association['type'] & ClassMetadata::TO_MANY &&
  344.             $this->owner &&
  345.             $this->association['orphanRemoval']
  346.         ) {
  347.             $this->em->getUnitOfWork()->scheduleOrphanRemoval($element);
  348.         }
  349.         return $removed;
  350.     }
  351.     /**
  352.      * {@inheritdoc}
  353.      */
  354.     public function containsKey($key): bool
  355.     {
  356.         if (
  357.             ! $this->initialized && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY
  358.             && isset($this->association['indexBy'])
  359.         ) {
  360.             $persister $this->em->getUnitOfWork()->getCollectionPersister($this->association);
  361.             return $this->collection->containsKey($key) || $persister->containsKey($this$key);
  362.         }
  363.         return parent::containsKey($key);
  364.     }
  365.     /**
  366.      * {@inheritdoc}
  367.      */
  368.     public function contains($element): bool
  369.     {
  370.         if (! $this->initialized && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY) {
  371.             $persister $this->em->getUnitOfWork()->getCollectionPersister($this->association);
  372.             return $this->collection->contains($element) || $persister->contains($this$element);
  373.         }
  374.         return parent::contains($element);
  375.     }
  376.     /**
  377.      * {@inheritdoc}
  378.      */
  379.     public function get($key)
  380.     {
  381.         if (
  382.             ! $this->initialized
  383.             && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY
  384.             && isset($this->association['indexBy'])
  385.         ) {
  386.             if (! $this->typeClass->isIdentifierComposite && $this->typeClass->isIdentifier($this->association['indexBy'])) {
  387.                 return $this->em->find($this->typeClass->name$key);
  388.             }
  389.             return $this->em->getUnitOfWork()->getCollectionPersister($this->association)->get($this$key);
  390.         }
  391.         return parent::get($key);
  392.     }
  393.     public function count(): int
  394.     {
  395.         if (! $this->initialized && $this->association !== null && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY) {
  396.             $persister $this->em->getUnitOfWork()->getCollectionPersister($this->association);
  397.             return $persister->count($this) + ($this->isDirty $this->collection->count() : 0);
  398.         }
  399.         return parent::count();
  400.     }
  401.     /**
  402.      * {@inheritdoc}
  403.      */
  404.     public function set($key$value): void
  405.     {
  406.         parent::set($key$value);
  407.         $this->changed();
  408.         if (is_object($value) && $this->em) {
  409.             $this->em->getUnitOfWork()->cancelOrphanRemoval($value);
  410.         }
  411.     }
  412.     /**
  413.      * {@inheritdoc}
  414.      */
  415.     public function add($value): bool
  416.     {
  417.         $this->collection->add($value);
  418.         $this->changed();
  419.         if (is_object($value) && $this->em) {
  420.             $this->em->getUnitOfWork()->cancelOrphanRemoval($value);
  421.         }
  422.         return true;
  423.     }
  424.     /* ArrayAccess implementation */
  425.     /**
  426.      * {@inheritdoc}
  427.      */
  428.     public function offsetExists($offset): bool
  429.     {
  430.         return $this->containsKey($offset);
  431.     }
  432.     /**
  433.      * {@inheritdoc}
  434.      */
  435.     public function offsetGet($offset)
  436.     {
  437.         return $this->get($offset);
  438.     }
  439.     /**
  440.      * {@inheritdoc}
  441.      */
  442.     public function offsetSet($offset$value): void
  443.     {
  444.         if (! isset($offset)) {
  445.             $this->add($value);
  446.             return;
  447.         }
  448.         $this->set($offset$value);
  449.     }
  450.     /**
  451.      * {@inheritdoc}
  452.      *
  453.      * @return object|null
  454.      */
  455.     public function offsetUnset($offset)
  456.     {
  457.         return $this->remove($offset);
  458.     }
  459.     public function isEmpty(): bool
  460.     {
  461.         return $this->collection->isEmpty() && $this->count() === 0;
  462.     }
  463.     public function clear(): void
  464.     {
  465.         if ($this->initialized && $this->isEmpty()) {
  466.             $this->collection->clear();
  467.             return;
  468.         }
  469.         $uow $this->em->getUnitOfWork();
  470.         if (
  471.             $this->association['type'] & ClassMetadata::TO_MANY &&
  472.             $this->association['orphanRemoval'] &&
  473.             $this->owner
  474.         ) {
  475.             // we need to initialize here, as orphan removal acts like implicit cascadeRemove,
  476.             // hence for event listeners we need the objects in memory.
  477.             $this->initialize();
  478.             foreach ($this->collection as $element) {
  479.                 $uow->scheduleOrphanRemoval($element);
  480.             }
  481.         }
  482.         $this->collection->clear();
  483.         $this->initialized true// direct call, {@link initialize()} is too expensive
  484.         if ($this->association['isOwningSide'] && $this->owner) {
  485.             $this->changed();
  486.             $uow->scheduleCollectionDeletion($this);
  487.             $this->takeSnapshot();
  488.         }
  489.     }
  490.     /**
  491.      * Called by PHP when this collection is serialized. Ensures that only the
  492.      * elements are properly serialized.
  493.      *
  494.      * Internal note: Tried to implement Serializable first but that did not work well
  495.      *                with circular references. This solution seems simpler and works well.
  496.      *
  497.      * @return string[]
  498.      * @psalm-return array{0: string, 1: string}
  499.      */
  500.     public function __sleep(): array
  501.     {
  502.         return ['collection''initialized'];
  503.     }
  504.     /**
  505.      * Extracts a slice of $length elements starting at position $offset from the Collection.
  506.      *
  507.      * If $length is null it returns all elements from $offset to the end of the Collection.
  508.      * Keys have to be preserved by this method. Calling this method will only return the
  509.      * selected slice and NOT change the elements contained in the collection slice is called on.
  510.      *
  511.      * @param int      $offset
  512.      * @param int|null $length
  513.      *
  514.      * @return mixed[]
  515.      * @psalm-return array<TKey,T>
  516.      */
  517.     public function slice($offset$length null): array
  518.     {
  519.         if (! $this->initialized && ! $this->isDirty && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY) {
  520.             $persister $this->em->getUnitOfWork()->getCollectionPersister($this->association);
  521.             return $persister->slice($this$offset$length);
  522.         }
  523.         return parent::slice($offset$length);
  524.     }
  525.     /**
  526.      * Cleans up internal state of cloned persistent collection.
  527.      *
  528.      * The following problems have to be prevented:
  529.      * 1. Added entities are added to old PC
  530.      * 2. New collection is not dirty, if reused on other entity nothing
  531.      * changes.
  532.      * 3. Snapshot leads to invalid diffs being generated.
  533.      * 4. Lazy loading grabs entities from old owner object.
  534.      * 5. New collection is connected to old owner and leads to duplicate keys.
  535.      */
  536.     public function __clone()
  537.     {
  538.         if (is_object($this->collection)) {
  539.             $this->collection = clone $this->collection;
  540.         }
  541.         $this->initialize();
  542.         $this->owner    null;
  543.         $this->snapshot = [];
  544.         $this->changed();
  545.     }
  546.     /**
  547.      * Selects all elements from a selectable that match the expression and
  548.      * return a new collection containing these elements.
  549.      *
  550.      * @psalm-return Collection<TKey, T>
  551.      *
  552.      * @throws RuntimeException
  553.      */
  554.     public function matching(Criteria $criteria): Collection
  555.     {
  556.         if ($this->isDirty) {
  557.             $this->initialize();
  558.         }
  559.         if ($this->initialized) {
  560.             return $this->collection->matching($criteria);
  561.         }
  562.         if ($this->association['type'] === ClassMetadata::MANY_TO_MANY) {
  563.             $persister $this->em->getUnitOfWork()->getCollectionPersister($this->association);
  564.             return new ArrayCollection($persister->loadCriteria($this$criteria));
  565.         }
  566.         $builder         Criteria::expr();
  567.         $ownerExpression $builder->eq($this->backRefFieldName$this->owner);
  568.         $expression      $criteria->getWhereExpression();
  569.         $expression      $expression $builder->andX($expression$ownerExpression) : $ownerExpression;
  570.         $criteria = clone $criteria;
  571.         $criteria->where($expression);
  572.         $criteria->orderBy($criteria->getOrderings() ?: $this->association['orderBy'] ?? []);
  573.         $persister $this->em->getUnitOfWork()->getEntityPersister($this->association['targetEntity']);
  574.         return $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY
  575.             ? new LazyCriteriaCollection($persister$criteria)
  576.             : new ArrayCollection($persister->loadCriteria($criteria));
  577.     }
  578.     /**
  579.      * Retrieves the wrapped Collection instance.
  580.      *
  581.      * @return Collection<TKey, T>
  582.      */
  583.     public function unwrap(): Collection
  584.     {
  585.         return $this->collection;
  586.     }
  587.     protected function doInitialize(): void
  588.     {
  589.         // Has NEW objects added through add(). Remember them.
  590.         $newlyAddedDirtyObjects = [];
  591.         if ($this->isDirty) {
  592.             $newlyAddedDirtyObjects $this->collection->toArray();
  593.         }
  594.         $this->collection->clear();
  595.         $this->em->getUnitOfWork()->loadCollection($this);
  596.         $this->takeSnapshot();
  597.         if ($newlyAddedDirtyObjects) {
  598.             $this->restoreNewObjectsInDirtyCollection($newlyAddedDirtyObjects);
  599.         }
  600.     }
  601.     /**
  602.      * @param object[] $newObjects
  603.      *
  604.      * Note: the only reason why this entire looping/complexity is performed via `spl_object_hash`
  605.      *       is because we want to prevent using `array_udiff()`, which is likely to cause very
  606.      *       high overhead (complexity of O(n^2)). `array_diff_key()` performs the operation in
  607.      *       core, which is faster than using a callback for comparisons
  608.      */
  609.     private function restoreNewObjectsInDirtyCollection(array $newObjects): void
  610.     {
  611.         $loadedObjects               $this->collection->toArray();
  612.         $newObjectsByOid             array_combine(array_map('spl_object_hash'$newObjects), $newObjects);
  613.         $loadedObjectsByOid          array_combine(array_map('spl_object_hash'$loadedObjects), $loadedObjects);
  614.         $newObjectsThatWereNotLoaded array_diff_key($newObjectsByOid$loadedObjectsByOid);
  615.         if ($newObjectsThatWereNotLoaded) {
  616.             // Reattach NEW objects added through add(), if any.
  617.             array_walk($newObjectsThatWereNotLoaded, [$this->collection'add']);
  618.             $this->isDirty true;
  619.         }
  620.     }
  621. }