From 75821e75f502933bb61678b8b6ca10a4cbc8da7f Mon Sep 17 00:00:00 2001 From: Greg Bell Date: Sun, 21 May 2017 14:10:38 +1000 Subject: [PATCH] Clarify English and a few concepts - Globally change 'Shipping' to 'Shipment' - shipment is a noun and thus a clearer name for an object. - Move definition of unidirectional from example 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. --- docs/en/reference/association-mapping.rst | 91 ++++++++++++----------- 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/docs/en/reference/association-mapping.rst b/docs/en/reference/association-mapping.rst index a1a9f83a8..b1cfa22c8 100644 --- a/docs/en/reference/association-mapping.rst +++ b/docs/en/reference/association-mapping.rst @@ -16,6 +16,9 @@ This chapter is split into three different sections. - :ref:`association_mapping_defaults` are explained that simplify the use-case examples. - :ref:`collections` are introduced that contain entities in associations. +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 inverse sides of associations ` @@ -96,9 +99,7 @@ One-To-One, Unidirectional -------------------------- 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 -the ``Product`` so that the reference is said to be unidirectional, in one -direction only. +references one ``Shipment`` entity. .. configuration-block:: @@ -111,16 +112,16 @@ direction only. // ... /** - * @OneToOne(targetEntity="Shipping") - * @JoinColumn(name="shipping_id", referencedColumnName="id") + * @OneToOne(targetEntity="Shipment") + * @JoinColumn(name="shipment_id", referencedColumnName="id") */ - private $shipping; + private $shipment; // ... } /** @Entity */ - class Shipping + class Shipment { // ... } @@ -129,8 +130,8 @@ direction only. - - + + @@ -140,10 +141,10 @@ direction only. Product: type: entity oneToOne: - shipping: - targetEntity: Shipping + shipment: + targetEntity: Shipment joinColumn: - name: shipping_id + name: shipment_id referencedColumnName: id Note that the @JoinColumn is not really necessary in this example, @@ -155,15 +156,15 @@ Generated MySQL Schema: CREATE TABLE Product ( id INT AUTO_INCREMENT NOT NULL, - shipping_id INT DEFAULT NULL, - UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipping_id), + shipment_id INT DEFAULT NULL, + UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipment_id), PRIMARY KEY(id) ) ENGINE = InnoDB; - CREATE TABLE Shipping ( + CREATE TABLE Shipment ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) 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 ------------------------- @@ -172,6 +173,10 @@ Here is a one-to-one relationship between a ``Customer`` and a ``Cart``. The ``Cart`` has a reference back to the ``Customer`` so 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:: .. code-block:: php @@ -251,8 +256,9 @@ Generated MySQL Schema: ) ENGINE = InnoDB; ALTER TABLE Cart ADD FOREIGN KEY (customer_id) REFERENCES Customer(id); -See how the foreign key is defined on the owning side of the -relation, the table ``Cart``. +We had a choice of sides on which to place the ``mappedBy`` attribute. Because it +is on the ``Cart``, that is the owning side of the relation, and thus holds the +foreign key. One-To-One, Self-referencing ---------------------------- @@ -294,15 +300,16 @@ With the generated MySQL Schema: One-To-Many, Bidirectional -------------------------- -A one-to-many association has to be bidirectional, unless you are using an -additional join-table. This is necessary, because of the foreign key -in a one-to-many association being defined on the "many" side. Doctrine -needs a many-to-one association that defines the mapping of this -foreign key. +A one-to-many association has to be bidirectional, unless you are using a +join table. This is because the many side in a one-to-many association holds +the foreign key, making it the owning side. Doctrine needs the many side +defined in order to understand the association. This bidirectional mapping requires the ``mappedBy`` attribute on the -``OneToMany`` association and the ``inversedBy`` attribute on the ``ManyToOne`` -association. +"one" side and the "inversedBy" attribute on the "many" side. + +This means there is no difference between a bidirectional one-to-many and a +bidirectional many-to-one. .. configuration-block:: @@ -754,14 +761,14 @@ one is bidirectional. The MySQL schema is exactly the same as for the Many-To-Many 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 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 -from a developers perspective. You only have to ask yourself, which -entity is responsible for the connection management and pick that +from a developers perspective. You only have to ask yourself which +entity is responsible for the connection management, and pick that as the owning side. Take an example of two entities ``Article`` and ``Tag``. Whenever @@ -769,7 +776,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 you add a new article, you want to connect it with existing or new 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 understandable: @@ -883,14 +890,14 @@ As an example, consider this mapping: .. code-block:: php - + @@ -899,8 +906,8 @@ As an example, consider this mapping: Product: type: entity oneToOne: - shipping: - targetEntity: Shipping + shipment: + targetEntity: Shipment This is essentially the same as the following, more verbose, mapping: @@ -911,17 +918,17 @@ mapping: - - + + @@ -931,10 +938,10 @@ mapping: Product: type: entity oneToOne: - shipping: - targetEntity: Shipping + shipment: + targetEntity: Shipment joinColumn: - name: shipping_id + name: shipment_id referencedColumnName: id The @JoinTable definition used for many-to-many mappings has