RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2025-02-02 21:41:45 +03:00
Code Issues Projects Releases Wiki Activity

Clarify concepts, fix minor English issues.

Browse Source 
- Globally change 'Shipping' to 'Shipment' - shipment is a noun and thus a clearer name for an object.
- Add definition of unidirectional to the top of the document.
- Explain inversedBy and mappedBy the first time they are used.
- Clarify some ownership and bidirectionality text.
- Minor English and punctuation fixes.
This commit is contained in:
Greg Bell 2017-05-21 16:39:06 +10:00
parent ee066cc5de
commit 46cebfb33d
1 changed files with 51 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/en/reference/association-mapping.rst
View File

@ -24,6 +24,9 @@ One tip for working with relations is to read the relation from left to right, w
See below for all the possible relations. See below for all the possible relations.
An association is considered to be unidirectional if only one side of the association has
a property referring to the other side.
To gain a full understanding of associations you should also read about :doc:`owning and To gain a full understanding of associations you should also read about :doc:`owning and
inverse sides of associations <unitofwork-associations>` inverse sides of associations <unitofwork-associations>`
@ -105,9 +108,7 @@ One-To-One, Unidirectional
-------------------------- --------------------------
Here is an example of a one-to-one association with a ``Product`` entity that Here is an example of a one-to-one association with a ``Product`` entity that
references one ``Shipping`` entity. The ``Shipping`` does not reference back to references one ``Shipment`` entity.
the ``Product`` so that the reference is said to be unidirectional, in one
direction only.
.. configuration-block:: .. configuration-block::
@ -120,17 +121,17 @@ direction only.
// ... // ...
/** /**
* One Product has One Shipping. * One Product has One Shipment.
* @OneToOne(targetEntity="Shipping") * @OneToOne(targetEntity="Shipment")
* @JoinColumn(name="shipping_id", referencedColumnName="id") * @JoinColumn(name="shipment_id", referencedColumnName="id")
*/ */
private $shipping; private $shipment;
// ... // ...
} }
/** @Entity */ /** @Entity */
class Shipping class Shipment
{ {
// ... // ...
} }
@ -139,8 +140,8 @@ direction only.
<doctrine-mapping> <doctrine-mapping>
<entity class="Product"> <entity class="Product">
<one-to-one field="shipping" target-entity="Shipping"> <one-to-one field="shipment" target-entity="Shipment">
<join-column name="shipping_id" referenced-column-name="id" /> <join-column name="shipment_id" referenced-column-name="id" />
</one-to-one> </one-to-one>
</entity> </entity>
</doctrine-mapping> </doctrine-mapping>
@ -150,10 +151,10 @@ direction only.
Product: Product:
type: entity type: entity
oneToOne: oneToOne:
shipping: shipment:
targetEntity: Shipping targetEntity: Shipment
joinColumn: joinColumn:
name: shipping_id name: shipment_id
referencedColumnName: id referencedColumnName: id
Note that the @JoinColumn is not really necessary in this example, Note that the @JoinColumn is not really necessary in this example,
@ -165,15 +166,15 @@ Generated MySQL Schema:
CREATE TABLE Product ( CREATE TABLE Product (
id INT AUTO_INCREMENT NOT NULL, id INT AUTO_INCREMENT NOT NULL,
shipping_id INT DEFAULT NULL, shipment_id INT DEFAULT NULL,
UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipping_id), UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipment_id),
PRIMARY KEY(id) PRIMARY KEY(id)
) ENGINE = InnoDB; ) ENGINE = InnoDB;
CREATE TABLE Shipping ( CREATE TABLE Shipment (
id INT AUTO_INCREMENT NOT NULL, id INT AUTO_INCREMENT NOT NULL,
PRIMARY KEY(id) PRIMARY KEY(id)
) ENGINE = InnoDB; ) ENGINE = InnoDB;
ALTER TABLE Product ADD FOREIGN KEY (shipping_id) REFERENCES Shipping(id); ALTER TABLE Product ADD FOREIGN KEY (shipment_id) REFERENCES Shipment(id);
One-To-One, Bidirectional One-To-One, Bidirectional
------------------------- -------------------------
@ -182,6 +183,10 @@ Here is a one-to-one relationship between a ``Customer`` and a
``Cart``. The ``Cart`` has a reference back to the ``Customer`` so ``Cart``. The ``Cart`` has a reference back to the ``Customer`` so
it is bidirectional. it is bidirectional.
Here we see the ``mappedBy`` and ``inversedBy`` annotations for the first time.
They are used to tell Doctrine which property on the other side refers to the
object.
.. configuration-block:: .. configuration-block::
.. code-block:: php .. code-block:: php
@ -263,8 +268,9 @@ Generated MySQL Schema:
) ENGINE = InnoDB; ) ENGINE = InnoDB;
ALTER TABLE Cart ADD FOREIGN KEY (customer_id) REFERENCES Customer(id); ALTER TABLE Cart ADD FOREIGN KEY (customer_id) REFERENCES Customer(id);
See how the foreign key is defined on the owning side of the We had a choice of sides on which to place the ``mappedBy`` attribute. Because it
relation, the table ``Cart``. is on the ``Cart``, that is the owning side of the relation, and thus holds the
foreign key.
One-To-One, Self-referencing One-To-One, Self-referencing
---------------------------- ----------------------------
@ -307,15 +313,16 @@ With the generated MySQL Schema:
One-To-Many, Bidirectional One-To-Many, Bidirectional
-------------------------- --------------------------
A one-to-many association has to be bidirectional, unless you are using an A one-to-many association has to be bidirectional, unless you are using a
additional join-table. This is necessary, because of the foreign key join table. This is because the many side in a one-to-many association holds
in a one-to-many association being defined on the "many" side. Doctrine the foreign key, making it the owning side. Doctrine needs the many side
needs a many-to-one association that defines the mapping of this defined in order to understand the association.
foreign key.
This bidirectional mapping requires the ``mappedBy`` attribute on the This bidirectional mapping requires the ``mappedBy`` attribute on the
``OneToMany`` association and the ``inversedBy`` attribute on the ``ManyToOne`` "one" side and the ``inversedBy`` attribute on the "many" side.
association.
This means there is no difference between a bidirectional one-to-many and a
bidirectional many-to-one.
.. configuration-block:: .. configuration-block::
@ -775,14 +782,14 @@ one is bidirectional.
The MySQL schema is exactly the same as for the Many-To-Many The MySQL schema is exactly the same as for the Many-To-Many
uni-directional case above. uni-directional case above.
Owning and Inverse Side on a ManyToMany association Owning and Inverse Side on a ManyToMany Association
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For Many-To-Many associations you can chose which entity is the For Many-To-Many associations you can chose which entity is the
owning and which the inverse side. There is a very simple semantic owning and which the inverse side. There is a very simple semantic
rule to decide which side is more suitable to be the owning side rule to decide which side is more suitable to be the owning side
from a developers perspective. You only have to ask yourself, which from a developers perspective. You only have to ask yourself which
entity is responsible for the connection management and pick that entity is responsible for the connection management, and pick that
as the owning side. as the owning side.
Take an example of two entities ``Article`` and ``Tag``. Whenever Take an example of two entities ``Article`` and ``Tag``. Whenever
@ -790,7 +797,7 @@ you want to connect an Article to a Tag and vice-versa, it is
mostly the Article that is responsible for this relation. Whenever mostly the Article that is responsible for this relation. Whenever
you add a new article, you want to connect it with existing or new you add a new article, you want to connect it with existing or new
tags. Your create Article form will probably support this notion tags. Your create Article form will probably support this notion
and allow to specify the tags directly. This is why you should pick and allow specifying the tags directly. This is why you should pick
the Article as owning side, as it makes the code more the Article as owning side, as it makes the code more
understandable: understandable:
@ -906,14 +913,14 @@ As an example, consider this mapping:
.. code-block:: php .. code-block:: php
<?php <?php
/** @OneToOne(targetEntity="Shipping") */ /** @OneToOne(targetEntity="Shipment") */
private $shipping; private $shipment;
.. code-block:: xml .. code-block:: xml
<doctrine-mapping> <doctrine-mapping>
<entity class="Product"> <entity class="Product">
<one-to-one field="shipping" target-entity="Shipping" /> <one-to-one field="shipment" target-entity="Shipment" />
</entity> </entity>
</doctrine-mapping> </doctrine-mapping>
@ -922,8 +929,8 @@ As an example, consider this mapping:
Product: Product:
type: entity type: entity
oneToOne: oneToOne:
shipping: shipment:
targetEntity: Shipping targetEntity: Shipment
This is essentially the same as the following, more verbose, This is essentially the same as the following, more verbose,
mapping: mapping:
@ -934,18 +941,18 @@ mapping:
<?php <?php
/** /**
* One Product has One Shipping. * One Product has One Shipment.
* @OneToOne(targetEntity="Shipping") * @OneToOne(targetEntity="Shipment")
* @JoinColumn(name="shipping_id", referencedColumnName="id") * @JoinColumn(name="shipment_id", referencedColumnName="id")
*/ */
private $shipping; private $shipment;
.. code-block:: xml .. code-block:: xml
<doctrine-mapping> <doctrine-mapping>
<entity class="Product"> <entity class="Product">
<one-to-one field="shipping" target-entity="Shipping"> <one-to-one field="shipment" target-entity="Shipment">
<join-column name="shipping_id" referenced-column-name="id" /> <join-column name="shipment_id" referenced-column-name="id" />
</one-to-one> </one-to-one>
</entity> </entity>
</doctrine-mapping> </doctrine-mapping>
@ -955,10 +962,10 @@ mapping:
Product: Product:
type: entity type: entity
oneToOne: oneToOne:
shipping: shipment:
targetEntity: Shipping targetEntity: Shipment
joinColumn: joinColumn:
name: shipping_id name: shipment_id
referencedColumnName: id referencedColumnName: id
The @JoinTable definition used for many-to-many mappings has The @JoinTable definition used for many-to-many mappings has