What is the difference between inversedBy and mappedBy?
Blog
15 November 2026
3 min read
Stefan Bogdanescu
Founder & Senior Architect
In Doctrine, bidirectional relationships require two sides to the conversation: the owning side and the inverse (or non-owning) side. The confusion often stems from thinking these annotations define the physical database schema or the direction of data flow in a query. They do not. Instead, they tell Doctrine which property manages the foreign key and how to navigate back to the parent entity.
The `mappedBy` annotation belongs exclusively on the owning side of a relationship. This is the entity that contains the actual foreign key column in the database. By marking a property with `mappedBy`, you are explicitly stating, "I am not managing this relationship; I am being referenced by another entity." When Doctrine sees `mappedBy="customer"`, it knows to look for a field named `customer` on the related entity to maintain the link. In your example, the `$user` property uses `mappedBy="customer"` because the `users` table likely holds a `company_id` column that points back to the `companies` table. The User is the child in this hierarchy, and its persistence depends entirely on the Company's primary key.
Conversely, the `inversedBy` annotation goes on the non-owning side. This is the parent entity that contains the foreign key definition (usually via `@ORM\JoinColumn`). You use `inversedBy="user"` on the Company entity to tell Doctrine, "There are many Users pointing back to me." This annotation allows you to access the collection of children without defining a foreign key column in the parent table. It is purely a navigational hint for Doctrine's UnitOfWork. If you omit `inversedBy` on the parent side while using `mappedBy` on the child, Doctrine still knows how to load the data, but it cannot easily manage the state of the relationship or access the collection via the parent if the mapping isn't complete.
You should use neither when defining a unidirectional relationship or in specific cases involving lazy loading where you intentionally want to avoid maintaining the bidirectional link. For instance, if your API only ever needs to fetch a list of users and never expects a user to have a reference back to their company within the data payload, you might define the relationship only on the User side (`@ORM\ManyToOne`) without `mappedBy` or `inversedBy`. However, this creates a one-way street: you can find the User from the Company, but if you have an instance of the User object in memory and try to access its Company, Doctrine will not know how to resolve that navigation path unless you explicitly define it.
In your specific code snippet, the first relationship between `Person` and the implicit parent uses `mappedBy="customer"`. This confirms that the Person table holds the foreign key referencing the customer. The second relationship shows a standard owning side with `@ORM\JoinColumn`, meaning that table owns the column. The third example on `$company` demonstrates the classic pattern: the Company entity owns the foreign key (`companyID`) and uses `inversedBy="customer"` to acknowledge that multiple customers point to it.
A common pitfall is applying both `mappedBy` and `inversedBy` to the same property or forgetting one side entirely, which breaks lazy loading. If you are using Laravel alongside Doctrine, similar concepts apply in their respective ecosystems; for example, Eloquent handles inverse relationships automatically through accessor methods, whereas Doctrine requires these explicit annotations to maintain state consistency during transactions. Understanding which side holds the foreign key is the only way to determine where `mappedBy` belongs, ensuring that your UnitOfWork correctly tracks changes without generating unnecessary SQL updates.