Doctrine ORM 关联映射（Association Mapping）完全指南：从外键到对象引用的双向转换实战

数据库ORM后端【免费下载链接】ormDoctrine Object Relational Mapper (ORM)项目地址https://gitcode.com/gh_mirrors/or/orm点击查看免费下载导读本文是 Doctrine Object Relational Mapper (ORM) 官方参考文档中 association-mapping.rst 的深度展开版本系统讲解如何在实体之间建立一对一OneToOne、一对多OneToMany、多对一ManyToOne、多对多ManyToMany关联并覆盖单向/双向、自引用、拥有方owning side与反向方inverse side判定、映射默认值以及集合Collection初始化等核心议题。读完本文你将掌握用属性Attributes或 XML 声明各类关联的完整写法、mappedBy/inversedBy/JoinColumn/JoinTable的正确语义、默认命名规则以及如何避免最常见的关联陷阱。核心思想用对象引用取代外键在使用 Doctrine ORM 时你的业务代码中永远不需要直接操作外键而是始终持有对目标对象的引用Doctrine 会在内部把对象引用转换成数据库外键对单个对象的引用 → 表示为一条外键foreign key对对象集合的引用 → 表示为多条指向持有该集合的对象的外键。因此本章的实用阅读技巧是从左向右读关联名左边的词指的是当前实体。例如关联含义OneToMany当前实体的一个实例拥有被引用实体的多个实例ManyToOne当前实体的多个实例引用被引用实体的一个实例OneToOne当前实体的一个实例引用被引用实体的一个实例如果关联只有一侧持有指向另一侧的属性则该关联被称为**单向unidirectional关联如果两侧都持有引用则为双向bidirectional**关联。要完整理解关联建议同时阅读文档 unitofwork-associations.rst 中关于拥有方与反向方的详细说明。复合外键Composite Foreign Keys当目标实体拥有复合主键时需要为复合主键的每一列分别声明一个 join column 映射详见教程 composite-primary-keys.rst。ManyToOne单向关联最常用多对一关联是对象间最常见的关联形态。典型例子多个 User 拥有同一个 Address。使用 PHP 属性声明#[Entity] class User { // ... #[ManyToOne(targetEntity: Address::class)] #[JoinColumn(name: address_id, referencedColumnName: id)] private Address|null $address null; } #[Entity] class Address { // ... }等价的 XML 声明doctrine-mapping entity nameUser many-to-one fieldaddress target-entityAddress join-column nameaddress_id referenced-column-nameid / /many-to-one /entity /doctrine-mapping注意上面的#[JoinColumn]其实是可以省略的因为默认值恰好就是address_id和id#[ManyToOne]中的targetEntity也可以省略并默认推断为Address。省略细节见下文「映射默认值」小节。生成的 MySQL SchemaCREATE TABLE User ( id INT AUTO_INCREMENT NOT NULL, address_id INT DEFAULT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE Address ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE User ADD FOREIGN KEY (address_id) REFERENCES Address(id);从源码看#[ManyToOne]属性在 src/Mapping/ManyToOne.php 中声明了targetEntity、cascade、fetch默认LAZY和inversedBy四个参数其中targetEntity与inversedBy均可为null前者配合类型推断、后者用于双向关联时声明反向方。OneToOne单向、双向与自引用单向 OneToOne一个Product实体引用一个Shipment实体#[Entity] class Product { // ... /** One Product has One Shipment. */ #[OneToOne(targetEntity: Shipment::class)] #[JoinColumn(name: shipment_id, referencedColumnName: id)] private Shipment|null $shipment null; // ... } #[Entity] class Shipment { // ... }等价的 XMLdoctrine-mapping entity classProduct one-to-one fieldshipment target-entityShipment join-column nameshipment_id referenced-column-nameid / /one-to-one /entity /doctrine-mapping生成的 MySQL Schema注意外键列上的UNIQUE 索引保证了“一对一”基数CREATE TABLE Product ( id INT AUTO_INCREMENT NOT NULL, shipment_id INT DEFAULT NULL, UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipment_id), PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE Shipment ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE Product ADD FOREIGN KEY (shipment_id) REFERENCES Shipment(id);双向 OneToOnemappedBy 与 inversedBy 首次登场Customer与Cart是一对一关系Cart持有对Customer的反向引用因此是双向的。这里首次出现mappedBy与inversedBy它们用来告诉 Doctrine另一侧的哪个属性指向本对象#[Entity] class Customer { // ... /** One Customer has One Cart. */ #[OneToOne(targetEntity: Cart::class, mappedBy: customer)] private Cart|null $cart null; // ... } #[Entity] class Cart { // ... /** One Cart has One Customer. */ #[OneToOne(targetEntity: Customer::class, inversedBy: cart)] #[JoinColumn(name: customer_id, referencedColumnName: id)] private Customer|null $customer null; // ... }等价的 XMLdoctrine-mapping entity nameCustomer one-to-one fieldcart target-entityCart mapped-bycustomer / /entity entity nameCart one-to-one fieldcustomer target-entityCustomer inversed-bycart join-column namecustomer_id referenced-column-nameid / /one-to-one /entity /doctrine-mapping生成 SchemaCREATE TABLE Cart ( id INT AUTO_INCREMENT NOT NULL, customer_id INT DEFAULT NULL, UNIQUE INDEX UNIQ_BA388B79395C3F3 (customer_id), PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE Customer ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE Cart ADD FOREIGN KEY (customer_id) REFERENCES Customer(id);关键结论inversedBy放在哪一侧哪一侧就是拥有方owning side并持有外键。本例中外键落在Cart表上。自引用 OneToOne实体也可以引用自身#[Entity] class Student { // ... /** One Student has One Mentor. */ #[OneToOne(targetEntity: Student::class)] #[JoinColumn(name: mentor_id, referencedColumnName: id)] private Student|null $mentor null; // ... }生成 SchemaCREATE TABLE Student ( id INT AUTO_INCREMENT NOT NULL, mentor_id INT DEFAULT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE Student ADD FOREIGN KEY (mentor_id) REFERENCES Student(id);OneToMany双向标准形态与带连接表的单向双向 OneToMany与 ManyToOne 是同一枚硬币的两面一对多关联必须是双向的除非使用连接表。原因在于一对多中“多”的一侧持有外键是拥有方Doctrine 必须看到“多”的一侧ManyToOne才能理解这个关联。这种双向映射要求在“一”侧使用mappedBy在“多”侧使用inversedBy。因此双向 OneToMany 与双向 ManyToOne 在本质上是同一个关联。use Doctrine\Common\Collections\ArrayCollection; #[Entity] class Product { // ... /** * One product has many features. This is the inverse side. * var Collectionint, Feature */ #[OneToMany(targetEntity: Feature::class, mappedBy: product)] private Collection $features; // ... public function __construct() { $this-features new ArrayCollection(); } } #[Entity] class Feature { // ... /** Many features have one product. This is the owning side. */ #[ManyToOne(targetEntity: Product::class, inversedBy: features)] #[JoinColumn(name: product_id, referencedColumnName: id)] private Product|null $product null; // ... }等价的 XMLdoctrine-mapping entity nameProduct one-to-many fieldfeatures target-entityFeature mapped-byproduct / /entity entity nameFeature many-to-one fieldproduct target-entityProduct inversed-byfeatures join-column nameproduct_id referenced-column-nameid / /many-to-one /entity /doctrine-mapping生成 Schema外键在Feature表上CREATE TABLE Product ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE Feature ( id INT AUTO_INCREMENT NOT NULL, product_id INT DEFAULT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE Feature ADD FOREIGN KEY (product_id) REFERENCES Product(id);#[OneToMany]在 src/Mapping/OneToMany.php 中除了targetEntity、mappedBy之外还支持cascade、fetch默认LAZY、orphanRemoval以及indexBy#[ManyToOne]则支持inversedBy、cascade、fetch。单向 OneToMany with Join Table单向的一对多可以通过连接表映射。从 Doctrine 的角度看它本质上就是单向多对多只是在其中一个 join column 上加唯一约束来强制“一对多”的基数。下面的例子建立了User到Phonenumber的单向一对多#[Entity] class User { // ... /** * Many Users have Many Phonenumbers. * var Collectionint, Phonenumber */ #[JoinTable(name: users_phonenumbers)] #[JoinColumn(name: user_id, referencedColumnName: id)] #[InverseJoinColumn(name: phonenumber_id, referencedColumnName: id, unique: true)] #[ManyToMany(targetEntity: Phonenumber)] private Collection $phonenumbers; public function __construct() { $this-phonenumbers new ArrayCollection(); } // ... } #[Entity] class Phonenumber { // ... }等价的 XMLdoctrine-mapping entity nameUser many-to-many fieldphonenumbers target-entityPhonenumber join-table nameusers_phonenumbers join-columns join-column nameuser_id referenced-column-nameid / /join-columns inverse-join-columns join-column namephonenumber_id referenced-column-nameid uniquetrue / /inverse-join-columns /join-table /many-to-many /entity /doctrine-mapping生成 Schema注意phonenumber_id上的唯一索引CREATE TABLE User ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE users_phonenumbers ( user_id INT NOT NULL, phonenumber_id INT NOT NULL, UNIQUE INDEX users_phonenumbers_phonenumber_id_uniq (phonenumber_id), PRIMARY KEY(user_id, phonenumber_id) ) ENGINE InnoDB; CREATE TABLE Phonenumber ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE users_phonenumbers ADD FOREIGN KEY (user_id) REFERENCES User(id); ALTER TABLE users_phonenumbers ADD FOREIGN KEY (phonenumber_id) REFERENCES Phonenumber(id);自引用 OneToMany邻接表Adjacency List建模树形结构通过自引用的一对多可以建立Category对象的层级结构这在数据库视角被称为邻接表方案#[Entity] class Category { // ... /** * One Category has Many Categories. * var Collectionint, Category */ #[OneToMany(targetEntity: Category::class, mappedBy: parent)] private Collection $children; /** Many Categories have One Category. */ #[ManyToOne(targetEntity: Category::class, inversedBy: children)] #[JoinColumn(name: parent_id, referencedColumnName: id)] private Category|null $parent null; // ... public function __construct() { $this-children new ArrayCollection(); } }等价的 XMLdoctrine-mapping entity nameCategory one-to-many fieldchildren target-entityCategory mapped-byparent / many-to-one fieldparent target-entityCategory inversed-bychildren / /entity /doctrine-mapping生成 SchemaCREATE TABLE Category ( id INT AUTO_INCREMENT NOT NULL, parent_id INT DEFAULT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE Category ADD FOREIGN KEY (parent_id) REFERENCES Category(id);ManyToMany单向、双向与自引用单向 ManyToMany真正的多对多关联相对少见。下面是一个User与Group之间的单向关联#[Entity] class User { // ... /** * Many Users have Many Groups. * var Collectionint, Group */ #[JoinTable(name: users_groups)] #[JoinColumn(name: user_id, referencedColumnName: id)] #[InverseJoinColumn(name: group_id, referencedColumnName: id)] #[ManyToMany(targetEntity: Group::class)] private Collection $groups; // ... public function __construct() { $this-groups new ArrayCollection(); } } #[Entity] class Group { // ... }等价的 XMLdoctrine-mapping entity nameUser many-to-many fieldgroups target-entityGroup join-table nameusers_groups join-columns join-column nameuser_id referenced-column-nameid / /join-columns inverse-join-columns join-column namegroup_id referenced-column-nameid / /inverse-join-columns /join-table /many-to-many /entity /doctrine-mapping生成 Schema连接表主键由两列共同构成CREATE TABLE User ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE users_groups ( user_id INT NOT NULL, group_id INT NOT NULL, PRIMARY KEY(user_id, group_id) ) ENGINE InnoDB; CREATE TABLE Group ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; ALTER TABLE users_groups ADD FOREIGN KEY (user_id) REFERENCES User(id); ALTER TABLE users_groups ADD FOREIGN KEY (group_id) REFERENCES Group(id);为什么多对多不常用因为通常你想为关联本身附加额外的属性这时应该引入一个“关联类association class”于是直接的多对多会消失被三个参与类之间的 OneToMany/ManyToOne 所取代。连接表管理Join Table Management对于多对多关联ORM 负责管理连接表中连接两侧的行。由于它处理实体删除的方式数据库层面的约束可能不会像直觉那样工作因此务必阅读 unitofwork-associations.rst 中关于多对多连接表删除处理的章节。双向 ManyToMany与上面相似只是这次是双向的#[Entity] class User { // ... /** * Many Users have Many Groups. * var Collectionint, Group */ #[ManyToMany(targetEntity: Group::class, inversedBy: users)] #[JoinTable(name: users_groups)] private Collection $groups; public function __construct() { $this-groups new ArrayCollection(); } // ... } #[Entity] class Group { // ... /** * Many Groups have Many Users. * var Collectionint, User */ #[ManyToMany(targetEntity: User::class, mappedBy: groups)] private Collection $users; public function __construct() { $this-users new ArrayCollection(); } // ... }等价的 XMLdoctrine-mapping entity nameUser many-to-many fieldgroups inversed-byusers target-entityGroup join-table nameusers_groups join-columns join-column nameuser_id referenced-column-nameid / /join-columns inverse-join-columns join-column namegroup_id referenced-column-nameid / /inverse-join-columns /join-table /many-to-many /entity entity nameGroup many-to-many fieldusers mapped-bygroups target-entityUser/ /entity /doctrine-mapping生成的 MySQL Schema 与上面单向多对多完全相同——双向与单向的数据库结构并无区别区别只存在于 ORM 层的同步维护逻辑。如何选择 ManyToMany 的拥有方与反向方对于多对多关联你可以选择哪个实体作为拥有方、哪个作为反向方。有一个非常简单的语义规则问自己哪个实体负责连接管理就把哪个实体作为拥有方。以Article与Tag为例每当你想把一篇文章与标签或反之连接起来时通常是 Article 承担这个职责——新建文章时把已有或新建的标签挂上去“创建文章”的表单也往往直接支持指定标签。因此把 Article 作为拥有方会让代码更易理解class Article { private Collection $tags; public function addTag(Tag $tag): void { $tag-addArticle($this); // synchronously updating inverse side $this-tags[] $tag; } } class Tag { private Collection $articles; public function addArticle(Article $article): void { $this-articles[] $article; } }这样可以在 Article 一侧统一完成标签的添加$article new Article(); $article-addTag($tagA); $article-addTag($tagB);注意addTag()中“同步更新反向方”的习惯做法——手动维护双向关联两侧的集合一致性是避免脏检查遗漏的常用技巧。自引用 ManyToMany好友关系自引用多对多也很常见典型场景是“用户的好友”目标实体仍是User。下面这个例子是双向的User同时拥有$friendsWithMe反向方mappedBy: myFriends和$myFriends拥有方声明JoinTable与两条JoinColumn#[Entity] class User { // ... /** * Many Users have Many Users. * var Collectionint, User */ #[ManyToMany(targetEntity: User::class, mappedBy: myFriends)] private Collection $friendsWithMe; /** * Many Users have many Users. * var Collectionint, User */ #[JoinTable(name: friends)] #[JoinColumn(name: user_id, referencedColumnName: id)] #[InverseJoinColumn(name: friend_user_id, referencedColumnName: id)] #[ManyToMany(targetEntity: User, inversedBy: friendsWithMe)] private Collection $myFriends; public function __construct() { $this-friendsWithMe new ArrayCollection(); $this-myFriends new ArrayCollection(); } // ... }生成 SchemaCREATE TABLE User ( id INT AUTO_INCREMENT NOT NULL, PRIMARY KEY(id) ) ENGINE InnoDB; CREATE TABLE friends ( user_id INT NOT NULL, friend_user_id INT NOT NULL, PRIMARY KEY(user_id, friend_user_id) ) ENGINE InnoDB; ALTER TABLE friends ADD FOREIGN KEY (user_id) REFERENCES User(id); ALTER TABLE friends ADD FOREIGN KEY (friend_user_id) REFERENCES User(id);映射默认值让映射代码缩减到最少JoinColumn与JoinTable定义通常都是可选的它们有合理的默认值。一对一/多对一关联中 join column 的默认值为name: fieldname_id referencedColumnName: id例如下面这个最简映射#[OneToOne(targetEntity: Shipment::class)] private Shipment|null $shipment null;等价于更啰嗦的完整写法/** One Product has One Shipment. */ #[OneToOne(targetEntity: Shipment::class)] #[JoinColumn(name: shipment_id, referencedColumnName: id)] private Shipment|null $shipment null;XML 版本同样如此doctrine-mapping entity classProduct one-to-one fieldshipment target-entityShipment / /entity /doctrine-mapping等价于doctrine-mapping entity classProduct one-to-one fieldshipment target-entityShipment join-column nameshipment_id referenced-column-nameid / /one-to-one /entity /doctrine-mappingJoinTable用于多对多也有类似的默认值。考虑这个最简映射class User { // ... /** var Collectionint, Group */ #[ManyToMany(targetEntity: Group::class)] private Collection $groups; // ... }它等价于class User { // ... /** * Many Users have Many Groups. * var Collectionint, Group */ #[JoinTable(name: User_Group)] #[JoinColumn(name: user_id, referencedColumnName: id)] #[InverseJoinColumn(name: group_id, referencedColumnName: id)] #[ManyToMany(targetEntity: Group::class)] private Collection $groups; // ... }默认值规则总结连接表名默认取参与关联的两个类简单类名不带命名空间用下划线连接例如User与Group得到User_Groupjoin column 名默认取目标类的简单类名后加_id例如目标类为Group则列名为group_idreferencedColumnName始终默认为id与一对一/多对一一致。类型化属性Typed Properties下的极简映射使用 Doctrine 2.9 或更新版本时ManyToOne与OneToOne关联中的targetEntity可以省略ORM 会根据属性的类型声明自动推断。于是#[OneToOne] private Shipment $shipment;等价于完整写法/** One Product has One Shipment. */ #[OneToOne(targetEntity: Shipment::class)] #[JoinColumn(name: shipment_id, referencedColumnName: id)] private Shipment $shipment;传统注解写法等价于OneToOne(targetEntityShipment) JoinColumn(nameshipment_id, referencedColumnNameid)。接受这些默认值即可把映射代码压缩到最少。JoinColumn 的完整参数面从源码 src/Mapping/JoinColumnProperties.php 可以看到JoinColumn/InverseJoinColumn除name与referencedColumnName外还支持参数说明deferrable是否可延迟默认falseunique是否唯一单向 OneToMany via join table 中用于强制基数nullable是否允许为 NULL默认为null即交由映射推断onDelete外键的 ON DELETE 动作如CASCADEcolumnDefinition直接指定列定义 DDLfieldName关联的字段名foreignKeyName外键约束名称options平台相关选项数组而 src/Mapping/JoinTable.php 中JoinTable还支持schema、joinColumns、inverseJoinColumns、foreignKeyName、inverseForeignKeyName与options。AssociationMapping基类src/Mapping/AssociationMapping.php则统一承载了cascadepersist/remove/detach/refresh/all与fetch默认LAZY等横切属性。集合Collections多值关联的必备类型很遗憾PHP 数组虽然在很多场景下很好用却缺少使其适合 ORM 场景下懒加载lazy loading的特性。因此本手册中所有多值关联的例子都使用Collection接口及其默认实现ArrayCollection两者定义在Doctrine\Common\Collections命名空间中。Collection实现了 PHP 的ArrayAccess、Traversable与Countable接口。重要说明Collection接口与ArrayCollection类和 Doctrine 命名空间中的其他东西一样既不属于 ORM 也不属于 DBAL——它是一个纯粹的 PHP 类除了 PHP 本身以及 SPL之外没有任何外部依赖。因此在你的模型和其他地方使用它不会引入对 ORM 的耦合。初始化集合在构造函数中完成你应该始终在实体的构造函数中初始化OneToMany与ManyToMany关联的集合use Doctrine\Common\Collections\Collection; use Doctrine\Common\Collections\ArrayCollection; #[Entity] class User { /** Many Users have Many Groups. */ #[ManyToMany(targetEntity: Group::class)] private Collection $groups; public function __construct() { $this-groups new ArrayCollection(); } public function getGroups(): Collection { return $this-groups; } }这样即使实体尚未与任何EntityManager关联下面的代码也能正常工作$group new Group(); $user new User(); $user-getGroups()-add($group);集合的继承语义ArrayCollection的add()会返回布尔值以指示是否发生变更且集合变更会被持久化层的变更追踪机制Change Tracking捕获。这也解释了为什么上述“同步更新双向关联两侧”的辅助方法如Article::addTag()非常关键只修改反向方集合而不修改拥有方可能导致脏检查漏判。小结与最佳实践对象引用即外键业务代码永远不碰外键Doctrine 负责转换左读右记OneToMany/ManyToOne/OneToOne都以当前实体为视角。双向关联必须成对声明一侧mappedBy、另一侧inversedBy拥有方持有外键OneToOne/OneToMany 中就是声明JoinColumn的那一侧inversedBy落在哪一侧哪一侧就是拥有方。OneToMany 默认必须双向除非通过连接表 唯一约束模拟单向一对多。多对多尽量考虑关联类需要为关联附加属性时用三个类之间的 OneToMany/ManyToOne 取代直接多对多。接受默认值field_id/id/Class_Class这些默认规则能让映射代码极简Doctrine 2.9 的类型化属性还能省去targetEntity。集合在构造函数初始化使用Collection/ArrayCollection与 ORM 解耦且天然支持懒加载。如需深入了解拥有方/反向方在持久化与删除时的具体行为尤其是多对多连接表的删除语义请继续阅读 unitofwork-associations.rst复合主键下的关联映射细节见 composite-primary-keys.rst。关联映射相关的全部 PHP 属性类ManyToOne、OneToOne、OneToMany、ManyToMany、JoinColumn、JoinTable、InverseJoinColumn等均可在 src/Mapping 目录中查看测试样例可参考 tests/Tests/Models 下的模型目录。赞分享数据库ORM后端【免费下载链接】ormDoctrine Object Relational Mapper (ORM)项目地址https://gitcode.com/gh_mirrors/or/orm点击查看免费下载相关推荐Doctrine ORM 关联Association实战指南从映射定义到集合操作与级联管理Doctrine ORM 关联Association实战指南从映射定义到集合操作与级联管理 本指南以 Doctrine ORM 官方参考文档 workin数据库ORM后端Doctrine ORM 对象映射完全教程用 PHP 8 Attributes 把对象轻松映射到数据库表Doctrine ORM 对象映射完全教程用 PHP 8 Attributes 把对象轻松映射到数据库表 Doctrine ORM 是 PHP 生态中最成熟的数据库ORM后端Apache Airflow Apache Cassandra Provider 完全指南连接配置与表/记录传感器实战Apache Airflow Apache Cassandra Provider 完全指南连接配置与表/记录传感器实战 本篇技术指南以 Apache Airf数据库ORM后端上一篇Trezor Firmware Monorepo完全指南从架构到安全的终极探索下一篇CircuitVerse 开源项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考