Documentation: mappedBy and inversedBy confusing explanation. #5687

New Issue

admin · 2026-01-22T15:14:31+01:00

admin commented

2026-01-22 15:14:31 +01:00

Originally created by @jelomada on GitHub (Sep 4, 2017).

I think this three sentences should be improved to be more unmistakable.

5.3:
"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."
11.1:
"The inverse side has to use the mappedBy attribute of the OneToOne, OneToMany, or ManyToMany mapping declaration."
"The owning side has to use the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. "

5.3 says: "Because mappedBy attribute is on the Cart, that is the owning side of the relation..." and 11.1 says: "the owning side has to use the inversedBy attribute..."

I know this is correct but maybe there is a way to write it more clearly.
The problem is that "owning side" once refers to owning entity class (11.1) and another time to target entity of relation declared inside inverse entity class (5.3).
It is really confusing.

Originally created by @jelomada on GitHub (Sep 4, 2017). I think this three sentences should be improved to be more unmistakable. 5.3: "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." 11.1: "The inverse side has to use the mappedBy attribute of the OneToOne, OneToMany, or ManyToMany mapping declaration." "The owning side has to use the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. " 5.3 says: "Because mappedBy attribute is on the Cart, that is the owning side of the relation..." and 11.1 says: "the owning side has to use the inversedBy attribute..." I know this is correct but maybe there is a way to write it more clearly. The problem is that "owning side" once refers to owning entity class (11.1) and another time to target entity of relation declared inside inverse entity class (5.3). It is really confusing.

admin closed this issue

2026-01-22 15:14:31 +01:00

admin commented

2026-01-22 15:14:32 +01:00

@bitwombat commented on GitHub (Sep 5, 2017):

The problem is that "owning side" once refers to owning entity class (11.1) and another time to target
entity of relation declared inside inverse entity class (5.3).

I think in both places it refers to the owning entity class.

It is really confusing.

I have created similar issues, and after a bit of clarification from the maintainers, made changes to the docs and issued a PR. Perhaps if you did the same - rewrote it in a way that was clearer to you - the discussion over the PR would be more productive.

I actually printed the Doctrine docs, put them in a binder, and wrote all over them. So I agree that the concepts are confusing, but I don't think the documentation is. It took me awhile to get my head around it.

Let's discuss over a PR.

@bitwombat commented on GitHub (Sep 5, 2017): > The problem is that "owning side" once refers to owning entity class (11.1) and another time to target > entity of relation declared inside inverse entity class (5.3). I think in both places it refers to the owning entity class. > It is really confusing. I have created similar issues, and after a bit of clarification from the maintainers, made changes to the docs and issued a PR. Perhaps if you did the same - rewrote it in a way that was clearer to you - the discussion over the PR would be more productive. I actually printed the Doctrine docs, put them in a binder, and wrote all over them. So I agree that the concepts are confusing, but I don't think the documentation is. It took me awhile to get my head around it. Let's discuss over a PR.

admin commented

2026-01-22 15:14:33 +01:00

@jelomada commented on GitHub (Sep 5, 2017):

Sorry, but I think creating PR by me is not very good idea.
My English is not so good and I don't want to murder that language.
If you already discussed this matter, maybe it has to be like it is.

Just for ending I will try explain it one more time.
If you think doc is OK, leave it and close this issue.
And thank you very much for your answering.

So the last explanation:
5.3 code:

<?php
/** @Entity */
class Customer
{
    // ...

    /**
     * One Customer has One Cart.
     * @OneToOne(targetEntity="Cart", mappedBy="customer")
     */
    private $cart;

    // ...
}

/** @Entity */
class Cart
{
    // ...

    /**
     * One Cart has One Customer.
     * @OneToOne(targetEntity="Customer", inversedBy="cart")
     * @JoinColumn(name="customer_id", referencedColumnName="id")
     */
    private $customer;

    // ...
}

In this example Cart Entity is the owning side, Customer Entity is the inverse side.
Doc says:
"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."
and it's OK I understand this.

Now go to 11.1:
"The owning side has to use the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. "
It means we have to put inversedBy attribute inside our owning side entity (Cart Entity) class declaration:

/** @Entity */
class Cart
{
    // ...
    /* @OneToOne(targetEntity="Customer", inversedBy="cart") */

Both phrases are understandable for me. But when I'm reading them one after another I'm getting confused and I have to spend a moment to figured it out.

My thinking process looks something like that:
11.1: OK, put the inversedBy attribute inside the owning entity class and point this attribute to the inverse entity (point to = targetEntity).
Then I read 5.3 and understand it like this:
"The Cart Entity is the owning side because it has the mappedBy attribute." (this is wrong thinking)
Wait a moment. 11.1 says the owning side must have the inversedBy attribute, not the mappedBy.
I look at the 5.3 sentence, at the code snippet, have to think awhile.
And finally:
5.3 doesn't mean the mappedBy attribute is inside the Cart Entity (owning side) class declaration.
It means the mappedBy attribute placed inside the Customer Entity (inverse side) points to the Cart Entity (owning side).

I don't know, maybe it's because of my weak English skills and perhaps it's clear for native English speakers. I wrote everything I could and I won't bother you any more :) Thanks for your help.

@jelomada commented on GitHub (Sep 5, 2017): Sorry, but I think creating PR by me is not very good idea. My English is not so good and I don't want to murder that language. If you already discussed this matter, maybe it has to be like it is. Just for ending I will try explain it one more time. If you think doc is OK, leave it and close this issue. And thank you very much for your answering. So the last explanation: 5.3 code: ``` <?php /** @Entity */ class Customer { // ... /** * One Customer has One Cart. * @OneToOne(targetEntity="Cart", mappedBy="customer") */ private $cart; // ... } /** @Entity */ class Cart { // ... /** * One Cart has One Customer. * @OneToOne(targetEntity="Customer", inversedBy="cart") * @JoinColumn(name="customer_id", referencedColumnName="id") */ private $customer; // ... } ``` In this example Cart Entity is the owning side, Customer Entity is the inverse side. Doc says: "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." and it's OK I understand this. Now go to 11.1: "The owning side has to use the inversedBy attribute of the OneToOne, ManyToOne, or ManyToMany mapping declaration. " It means we have to put inversedBy attribute inside our owning side entity (Cart Entity) class declaration: ``` /** @Entity */ class Cart { // ... /* @OneToOne(targetEntity="Customer", inversedBy="cart") */ ``` Both phrases are understandable for me. But when I'm reading them one after another I'm getting confused and I have to spend a moment to figured it out. My thinking process looks something like that: 11.1: OK, put the inversedBy attribute inside the owning entity class and point this attribute to the inverse entity (point to = targetEntity). Then I read 5.3 and understand it like this: "The Cart Entity is the owning side because it has the mappedBy attribute." (this is wrong thinking) Wait a moment. 11.1 says the owning side must have the inversedBy attribute, not the mappedBy. I look at the 5.3 sentence, at the code snippet, have to think awhile. And finally: 5.3 doesn't mean the mappedBy attribute is inside the Cart Entity (owning side) class declaration. It means the mappedBy attribute placed inside the Customer Entity (inverse side) points to the Cart Entity (owning side). I don't know, maybe it's because of my weak English skills and perhaps it's clear for native English speakers. I wrote everything I could and I won't bother you any more :) Thanks for your help.

admin commented

2026-01-22 15:14:33 +01:00

@bitwombat commented on GitHub (Sep 5, 2017):

Your English is fine, and your critical analysis of English is better than
mine :)

I understand what you mean now. I think there are two problems:

The documentation is using different words/phrases for similar things regarding where the attribute is: "on", "place", "use", "put...inside", and "has".
I agree this is either wrong or confusing:

"The Cart Entity is the owning side because it has the mappedBy attribute." (this is wrong thinking)

I've made a PR: #6690

See if it's clearer.

Thanks for your persistence - I thought I was the only one that obsessed over phrasing and
clarity of documentation :)

@bitwombat commented on GitHub (Sep 5, 2017): Your English is fine, and your critical analysis of English is better than mine :) I understand what you mean now. I think there are two problems: 1) The documentation is using different words/phrases for similar things regarding where the attribute is: "on", "place", "use", "put...inside", and "has". 2) I agree this is either wrong or confusing: > "The Cart Entity is the owning side because it has the mappedBy attribute." (this is wrong thinking) I've made a PR: #6690 See if it's clearer. Thanks for your persistence - I thought I was the only one that obsessed over phrasing and clarity of documentation :)

admin commented

2026-01-22 15:14:34 +01:00

@jelomada commented on GitHub (Sep 6, 2017):

Your English is fine, and your critical analysis of English is better than
mine :)

I don't think so but thanks for nice words :)

See if it's clearer.

It's great now.

Thanks for your persistence - I thought I was the only one that obsessed over phrasing and
clarity of documentation :)

I'm just stubborn and had to prove my point :)
I'm glad we've found understanding. Maybe it will spare a few frustrating moments for others.

@jelomada commented on GitHub (Sep 6, 2017): > Your English is fine, and your critical analysis of English is better than mine :) I don't think so but thanks for nice words :) > See if it's clearer. It's great now. > Thanks for your persistence - I thought I was the only one that obsessed over phrasing and clarity of documentation :) I'm just stubborn and had to prove my point :) I'm glad we've found understanding. Maybe it will spare a few frustrating moments for others.

admin commented

2026-01-22 15:14:34 +01:00

@bitwombat commented on GitHub (Sep 7, 2017):

@jelomada perhaps you can help clarify #6083 with me.

@bitwombat commented on GitHub (Sep 7, 2017): @jelomada perhaps you can help clarify #6083 with me.

admin commented

2026-01-22 15:14:34 +01:00

@bitwombat commented on GitHub (Sep 30, 2017):

PR #6690 has been merged. Please close.

@bitwombat commented on GitHub (Sep 30, 2017): PR #6690 has been merged. Please close.

admin commented

2026-01-22 15:14:35 +01:00

@holtkamp commented on GitHub (Sep 30, 2017):

Great work guys

I thought I was the only one that obsessed over phrasing and
clarity of documentation :)
I'm just stubborn and had to prove my point :)

I would say these are essential characteristics in a craftsman 🤓

@holtkamp commented on GitHub (Sep 30, 2017): Great work guys >I thought I was the only one that obsessed over phrasing and clarity of documentation :) >I'm just stubborn and had to prove my point :) I would say these are essential characteristics in a craftsman 🤓

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: doctrine/archived-orm#5687