You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.

How to Work with Doctrine Associations / Relations

4.2 version
Maintained Unmaintained

How to Work with Doctrine Associations / Relations

Screencast

Do you prefer video tutorials? Check out the Mastering Doctrine Relations screencast series.

There are two main relationship/association types:

ManyToOne / OneToMany
The most common relationship, mapped in the database with a foreign key column (e.g. a category_id column on the product table). This is actually just one association type, but seen from the two different sides of the relation.
ManyToMany
Uses a join table and is needed when both sides of the relationship can have many of the other side (e.g. "students" and "classes": each student is in many classes, and each class has many students).

First, you need to determine which relationship to use. If both sides of the relation will contain many of the other side (e.g. "students" and "classes"), you need a ManyToMany relation. Otherwise, you likely need a ManyToOne.

Tip

There is also a OneToOne relationship (e.g. one User has one Profile and vice versa). In practice, using this is similar to ManyToOne.

The ManyToOne / OneToMany Association

Suppose that each product in your application belongs to exactly one category. In this case, you'll need a Category class, and a way to relate a Product object to a Category object.

Start by creating a Category entity with a name field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
$ php bin/console make:entity Category

New property name (press <return> to stop adding fields):
> name

Field type (enter ? to see all types) [string]:
> string

Field length [255]:
> 255

Can this field be null in the database (nullable) (yes/no) [no]:
> no

New property name (press <return> to stop adding fields):
>
(press enter again to finish)

This will generate your new entity class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// src/Entity/Category.php
// ...

class Category
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string")
     */
    private $name;

    // ... getters and setters
}

Mapping the ManyToOne Relationship

In this example, each category can be associated with many products. But, each product can be associated with only one category. This relationship can be summarized as: many products to one category (or equivalently, one category to many products).

From the perspective of the Product entity, this is a many-to-one relationship. From the perspective of the Category entity, this is a one-to-many relationship.

To map this, first create a category property on the Product class with the ManyToOne annotation. You can do this by hand, or by using the make:entity command, which will ask you several questions about your relationship. If you're not sure of the answer, don't worry! You can always change the settings later:

 1
 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
28
29
30
31
32
33
34
$ php bin/console make:entity

Class name of the entity to create or update (e.g. BraveChef):
> Product

New property name (press <return> to stop adding fields):
> category

Field type (enter ? to see all types) [string]:
> relation

What class should this entity be related to?:
> Category

Relation type? [ManyToOne, OneToMany, ManyToMany, OneToOne]:
> ManyToOne

Is the Product.category property allowed to be null (nullable)? (yes/no) [yes]:
> no

Do you want to add a new property to Category so that you can access/update
Product objects from it - e.g. $category->getProducts()? (yes/no) [yes]:
> yes

New field name inside Category [products]:
> products

Do you want to automatically delete orphaned App\Entity\Product objects
(orphanRemoval)? (yes/no) [no]:
> no

New property name (press <return> to stop adding fields):
>
(press enter again to finish)

This made changes to two changes. First, added a new category property to the Product entity (and getter & setter methods):

  • Annotations
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    // src/Entity/Product.php
    
    // ...
    class Product
    {
        // ...
    
        /**
         * @ORM\ManyToOne(targetEntity="App\Entity\Category", inversedBy="products")
         */
        private $category;
    
        public function getCategory(): ?Category
        {
            return $this->category;
        }
    
        public function setCategory(?Category $category): self
        {
            $this->category = $category;
    
            return $this;
        }
    }
    
  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    # src/Resources/config/doctrine/Product.orm.yml
    App\Entity\Product:
        type: entity
        # ...
        manyToOne:
            category:
                targetEntity: App\Entity\Category
                inversedBy: products
                joinColumn:
                    nullable: false
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    <!-- src/Resources/config/doctrine/Product.orm.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
    
        <entity name="App\Entity\Product">
            <!-- ... -->
            <many-to-one
                field="category"
                target-entity="App\Entity\Category"
                inversed-by="products">
                <join-column nullable="false" />
            </many-to-one>
        </entity>
    </doctrine-mapping>
    

This ManyToOne mapping is required. It tells Doctrine to use the category_id column on the product table to relate each record in that table with a record in the category table.

Next, since one Category object will relate to many Product objects, the make:entity command also added a products property to the Category class that will hold these objects:

  • Annotations
     1
     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
    28
    29
    30
    // src/Entity/Category.php
    
    // ...
    use Doctrine\Common\Collections\ArrayCollection;
    use Doctrine\Common\Collections\Collection;
    
    class Category
    {
        // ...
    
        /**
         * @ORM\OneToMany(targetEntity="App\Entity\Product", mappedBy="category")
         */
        private $products;
    
        public function __construct()
        {
            $this->products = new ArrayCollection();
        }
    
        /**
         * @return Collection|Product[]
         */
        public function getProducts(): Collection
        {
            return $this->products;
        }
    
        // addProduct() and removeProduct() were also added
    }
    
  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    # src/Resources/config/doctrine/Category.orm.yml
    App\Entity\Category:
        type: entity
        # ...
        oneToMany:
            products:
                targetEntity: App\Entity\Product
                mappedBy: category
    # Don't forget to initialize the collection in
    # the __construct() method of the entity
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    <!-- src/Resources/config/doctrine/Category.orm.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
            http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
    
        <entity name="App\Entity\Category">
            <!-- ... -->
            <one-to-many
                field="products"
                target-entity="App\Entity\Product"
                mapped-by="category" />
    
            <!--
                don't forget to init the collection in
                the __construct() method of the entity
            -->
        </entity>
    </doctrine-mapping>
    

The ManyToOne mapping shown earlier is required, But, this OneToMany is optional: only add it if you want to be able to access the products that are related to a category (this is one of the questions make:entity asks you). In this example, it will be useful to be able to call $category->getProducts(). If you don't want it, then you also don't need the inversedBy or mappedBy config.

The code inside __construct() is important: The $products property must be a collection object that implements Doctrine's Collection interface. In this case, an ArrayCollection object is used. This looks and acts almost exactly like an array, but has some added flexibility. Just imagine that it's an array and you'll be in good shape.

Your database is setup! Now, execute the migrations like normal:

1
2
$ php bin/console doctrine:migrations:diff
$ php bin/console doctrine:migrations:migrate

Thanks to the relationship, this creates a category_id foreign key column on the product table. Doctrine is ready to persist our relationship!

Setting Information from the Inverse Side

So far, you've updated the relationship by calling $product->setCategory($category). This is no accident! Each relationship has two sides: in this example, Product.category is the owning side and Category.products is the inverse side.

To update a relationship in the database, you must set the relationship on the owning side. The owning side is always where the ManyToOne mapping is set (for a ManyToMany relation, you can choose which side is the owning side).

Does this means it's not possible to call $category->addProduct() or $category->removeProduct() to update the database? Actually, it is possible, thanks to some clever code that the make:entity command generated:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// src/Entity/Category.php

// ...
class Category
{
    // ...

    public function addProduct(Product $product): self
    {
        if (!$this->products->contains($product)) {
            $this->products[] = $product;
            $product->setCategory($this);
        }

        return $this;
    }
}

The key is $product->setCategory($this), which sets the owning side. Thanks, to this, when you save, the relationship will update in the database.

What about removing a Product from a Category? The make:entity command also generated a removeProduct() method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// src/Entity/Category.php

// ...
class Category
{
    // ...

    public function removeProduct(Product $product): self
    {
        if ($this->products->contains($product)) {
            $this->products->removeElement($product);
            // set the owning side to null (unless already changed)
            if ($product->getCategory() === $this) {
                $product->setCategory(null);
            }
        }

        return $this;
    }
}

Thanks to this, if you call $category->removeProduct($product), the category_id on that Product will be set to null in the database.

But, instead of setting the category_id to null, what if you want the Product to be deleted if it becomes "orphaned" (i.e. without a Category)? To choose that behavior, use the orphanRemoval option inside Category:

1
2
3
4
5
6
7
8
// src/Entity/Category.php

// ...

/**
 * @ORM\OneToMany(targetEntity="App\Entity\Product", mappedBy="category", orphanRemoval=true)
 */
private $products;

Thanks to this, if the Product is removed from the Category, it will be removed from the database entirely.

More Information on Associations

This section has been an introduction to one common type of entity relationship, the one-to-many relationship. For more advanced details and examples of how to use other types of relations (e.g. one-to-one, many-to-many), see Doctrine's Association Mapping Documentation.

Note

If you're using annotations, you'll need to prepend all annotations with @ORM\ (e.g. @ORM\OneToMany), which is not reflected in Doctrine's documentation.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.