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

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