diff --git a/en/reference/working-with-associations.rst b/en/reference/working-with-associations.rst index 9b34062f0..e49194e5b 100644 --- a/en/reference/working-with-associations.rst +++ b/en/reference/working-with-associations.rst @@ -517,4 +517,76 @@ that are found on already managed entities are automatically persisted as long as the association is defined as cascade persist. +Orphan Removal +-------------- +There is another concept of cascading that is relevant only when removing entities +from collections. If an Entity of type ``A`` contains references to privately +owned Entities ``B`` then if the reference from ``A`` to ``B`` is removed the +entity ``B`` should also be removed, because it is not used anymore. + +OrphanRemoval works with both one-to-one and one-to-many associations. + +.. note:: + + When using the ``orphanRemoval=true`` option Doctrine makes the assumption + that the entities are privately owned and will **NOT** be reused by other entities. + If you neglect this assumption your entities will get deleted by Doctrine anyways. + +As a better example consider an Addressbook application where you have Contacts, Addresses +and StandingData: + +.. code-block:: php + + addresses = new ArrayCollection(); + } + + public function newStandingData(StandingData $sd) + { + $this->standingData = $sd; + } + + public function removeAddress($pos) + { + unset($this->addresses[$pos]); + } + } + +Now two examples what happens when you remove the references: + +.. code-block:: php + + find("Addressbook\Contact", $contactId); + $contact->newStandingData(new StandingData("Firstname", "Lastname", "Street")); + $contact->removeAddress(1); + + $em->flush(); + +In this case you have only changed the ``Contact`` entity but you removed +the references for standing data and one address reference. When flush is called +not only are the references removed also both the old standing data and the one address entity +are deleted from the database.