Association Mapping

One-To-One, Unidirectional

A unidirectional one-to-one association is very common. Here is an example of a Product that has one Shipping object associated to it. The Shipping side does not reference back to the Product so it is unidirectional.

Note that the @JoinColumn is not really necessary in this example, as the defaults would be the same.

Generated MySQL Schema:

1
CREATE TABLE Product (
    id INT AUTO_INCREMENT NOT NULL,
    shipping_id INT DEFAULT NULL,
    UNIQUE INDEX UNIQ_6FBC94267FE4B2B (shipping_id),
    PRIMARY KEY(id)
) ENGINE = InnoDB;
CREATE TABLE Shipping (
    id INT AUTO_INCREMENT NOT NULL,
    PRIMARY KEY(id)
) ENGINE = InnoDB;
ALTER TABLE Product ADD FOREIGN KEY (shipping_id) REFERENCES Shipping(id);
2
3
4
5
6
7
8
9
10
11

One-To-One, Bidirectional

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.

Note that the @JoinColumn is not really necessary in this example, as the defaults would be the same.

Generated MySQL Schema:

1
CREATE TABLE Cart (
    id INT AUTO_INCREMENT NOT NULL,
    customer_id INT DEFAULT NULL,
    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);
2
3
4
5
6
7
8
9
10

See how the foreign key is defined on the owning side of the relation, the table Cart.

One-To-One, Self-referencing

You can easily have self referencing one-to-one relationships like below.

1
<?php
/** @Entity **/
class Student
{
    // ...

    /**
     * @OneToOne(targetEntity="Student")
     * @JoinColumn(name="mentor_id", referencedColumnName="id")
     **/
    private $mentor;

    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14

Note that the @JoinColumn is not really necessary in this example, as the defaults would be the same.

With the generated MySQL Schema:

1
CREATE 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);
2
3
4
5
6

One-To-Many, Unidirectional with Join Table

A unidirectional one-to-many association can be mapped through a join table. From Doctrine's point of view, it is simply mapped as a unidirectional many-to-many whereby a unique constraint on one of the join columns enforces the one-to-many cardinality.

The following example sets up such a unidirectional one-to-many association:

Generates the following MySQL Schema:

1
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);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Many-To-One, Unidirectional

You can easily implement a many-to-one unidirectional association with the following:

Generated MySQL Schema:

1
CREATE 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);
2
3
4
5
6
7
8
9
10
11
12

One-To-Many, Bidirectional

Bidirectional one-to-many associations are very common. The following code shows an example with a Product and a Feature class:

Note that the @JoinColumn is not really necessary in this example, as the defaults would be the same.

Generated MySQL Schema:

1
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);
2
3
4
5
6
7
8
9
10

One-To-Many, Self-referencing

You can also setup a one-to-many association that is self-referencing. In this example we setup a hierarchy of Category objects by creating a self referencing relationship. This effectively models a hierarchy of categories and from the database perspective is known as an adjacency list approach.

Note that the @JoinColumn is not really necessary in this example, as the defaults would be the same.

Generated MySQL Schema:

1
CREATE 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);
2
3
4
5
6

Many-To-Many, Unidirectional

Real many-to-many associations are less common. The following example shows a unidirectional association between User and Group entities:

Generated MySQL Schema:

1
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);
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Many-To-Many, Bidirectional

Here is a similar many-to-many relationship as above except this one is bidirectional.

The MySQL schema is exactly the same as for the Many-To-Many uni-directional case above.

1
<?php
class Article
{
    private $tags;

    public function addTag(Tag $tag)
    {
        $tag->addArticle($this); // synchronously updating inverse side
        $this->tags[] = $tag;
    }
}

class Tag
{
    private $articles;

    public function addArticle(Article $article)
    {
        $this->articles[] = $article;
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1
<?php
$article = new Article();
$article->addTag($tagA);
$article->addTag($tagB);
2
3
4

Many-To-Many, Self-referencing

You can even have a self-referencing many-to-many association. A common scenario is where a User has friends and the target entity of that relationship is a User so it is self referencing. In this example it is bidirectional so User has a field named $friendsWithMe and $myFriends.

1
<?php
/** @Entity **/
class User
{
    // ...

    /**
     * @ManyToMany(targetEntity="User", mappedBy="myFriends")
     **/
    private $friendsWithMe;

    /**
     * @ManyToMany(targetEntity="User", inversedBy="friendsWithMe")
     * @JoinTable(name="friends",
     *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
     *      inverseJoinColumns={@JoinColumn(name="friend_user_id", referencedColumnName="id")}
     *      )
     **/
    private $myFriends;

    public function __construct() {
        $this->friendsWithMe = new \Doctrine\Common\Collections\ArrayCollection();
        $this->myFriends = new \Doctrine\Common\Collections\ArrayCollection();
    }

    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Generated MySQL Schema:

1
CREATE 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);
2
3
4
5
6
7
8
9
10
11

Mapping Defaults

Before we introduce all the association mappings in detail, you should note that the @JoinColumn and @JoinTable definitions are usually optional and have sensible default values. The defaults for a join column in a one-to-one/many-to-one association is as follows:

name: "_id"
referencedColumnName: "id"

As an example, consider this mapping:

This is essentially the same as the following, more verbose, mapping:

The @JoinTable definition used for many-to-many mappings has similar defaults. As an example, consider this mapping:

This is essentially the same as the following, more verbose, mapping:

In that case, the name of the join table defaults to a combination of the simple, unqualified class names of the participating classes, separated by an underscore character. The names of the join columns default to the simple, unqualified class name of the targeted class followed by _id. The referencedColumnName always defaults to id, just as in one-to-one or many-to-one mappings.

If you accept these defaults, you can reduce the mapping code to a minimum.

Collections

In all the examples of many-valued associations in this manual we will make use of a Collection interface and a corresponding default implementation ArrayCollection that are defined in the Doctrine\Common\Collections namespace. Why do we need that? Doesn't that couple my domain model to Doctrine? Unfortunately, PHP arrays, while being great for many things, do not make up for good collections of business objects, especially not in the context of an ORM. The reason is that plain PHP arrays can not be transparently extended / instrumented in PHP code, which is necessary for a lot of advanced ORM features. The classes / interfaces that come closest to an OO collection are ArrayAccess and ArrayObject but until instances of these types can be used in all places where a plain array can be used (something that may happen in PHP6) their usability is fairly limited. You can type-hint on ArrayAccess instead of Collection, since the Collection interface extends ArrayAccess, but this will severely limit you in the way you can work with the collection, because the ArrayAccess API is (intentionally) very primitive and more importantly because you can not pass this collection to all the useful PHP array functions, which makes it very hard to work with.

Initializing Collections

You have to be careful when using entity fields that contain a collection of related entities. Say we have a User entity that contains a collection of groups:

1
<?php
/** @Entity **/
class User
{
    /** @ManyToMany(targetEntity="Group") **/
    private $groups;

    public function getGroups()
    {
        return $this->groups;
    }
}
2
3
4
5
6
7
8
9
10
11
12

With this code alone the $groups field only contains an instance of Doctrine\Common\Collections\Collection if the user is retrieved from Doctrine, however not after you instantiated a fresh instance of the User. When your user entity is still new $groups will obviously be null.

This is why we recommend to initialize all collection fields to an empty ArrayCollection in your entities constructor:

1
<?php
use Doctrine\Common\Collections\ArrayCollection;

/** @Entity **/
class User
{
    /** @ManyToMany(targetEntity="Group") **/
    private $groups;

    public function __construct()
    {
        $this->groups = new ArrayCollection();
    }

    public function getGroups()
    {
        return $this->groups;
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Now the following code will work even if the Entity hasn't been associated with an EntityManager yet:

1
<?php
$group = $entityManager->find('Group', $groupId);
$user = new User();
$user->getGroups()->add($group);
2
3
4