Maintained
2.10 (upcoming) 2.9.0 (current)
Unmaintained
2.8 2.7 2.6 2.5 2.4 2.3 2.2 2.1 2.0 1.3 1.2 1.1 1.0

Embedded Mapping

This chapter explains how embedded documents are mapped in Doctrine.

Embed One

Embed a single document:

1<?php

#[Document]
class User
{
    // ...

    #[EmbedOne(targetDocument: Address::class)]
    private ?Address $address;

    // ...
}

#[EmbeddedDocument]
class Address
{
    #[Field(type: 'string')]
    private string $street;

    // ...
}


2


3


4


5


6


7


8


9


10


11


12


13


14


15


16


17


18


19


20


21

Embed Many

Embed many documents:

1<?php

use Doctrine\Common\Collections\ArrayCollection;

#[Document]
class User
{
    // ...

    /** @var Collection<PhoneNumber> */
    #[EmbedMany(targetDocument: Phonenumber::class)]
    private Collection $phoneNumbers;

    // ...
    public function __construct()
    {
        $this->phoneNumbers = new ArrayCollection();
    }
}

#[EmbeddedDocument]
class PhoneNumber
{
    #[Field(type: 'string')]
    private string $number;

    // ...
}


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

Mixing Document Types

If you want to store different types of embedded documents in the same field, you can simply omit the targetDocument option:

1<?php

use Doctrine\Common\Collections\ArrayCollection;

#[Document]
class User
{
    // ..

    #[EmbedMany]
    private Collection $tasks;

    // ...
    public function __construct()
    {
        $this->tasks = new ArrayCollection();
    }
}


2


3


4


5


6


7


8


9


10


11


12


13


14


15


16


17


18

Now the $tasks property can store any type of document! The class name will be automatically stored in a field named _doctrine_class_name within the embedded document. The field name can be customized with the discriminatorField option:

1<?php

use Doctrine\Common\Collections\ArrayCollection;

#[Document]
class User
{
    // ..

    #[EmbedMany(discriminatorField: 'type')]
    private Collection $tasks;

    // ...
    public function __construct()
    {
        $this->tasks = new ArrayCollection();
    }
}


2


3


4


5


6


7


8


9


10


11


12


13


14


15


16


17


18

You can also specify a discriminator map to avoid storing the FQCN in each embedded document:

1<?php

use Doctrine\Common\Collections\ArrayCollection;

#[Document]
class User
{
    // ..

    #[EmbedMany(
      discriminatorMap: [
          'download' => DownloadTask::class,
          'build' => BuildTask::class,
      ]
    )]
    private Collection $tasks;

    // ...
    public function __construct()
    {
        $this->tasks = new ArrayCollection();
    }
}


2


3


4


5


6


7


8


9


10


11


12


13


14


15


16


17


18


19


20


21


22


23

If you have embedded documents without a discriminator value that need to be treated correctly you can optionally specify a default value for the discriminator:

1<?php

#[Document]
class User
{
    // ..

    #[EmbedMany(
        discriminatorMap: [
          'download' => DownloadTask::class,
          'build' => BuildTask::class,
        ],
        defaultDiscriminatorValue: 'download',
    )]
    private Collection $tasks;

    // ...
}


2


3


4


5


6


7


8


9


10


11


12


13


14


15


16


17


18

Cascading Operations

All operations on embedded documents are automatically cascaded. This is because embedded documents are part of their parent document and cannot exist without those by nature.

Storing Empty Arrays in Embedded Documents

By default, when an embedded collection property is empty, Doctrine does not store any data for it in the database. However, in some cases, you may want to explicitly store an empty array for such properties. You can achieve this behavior by using the storeEmptyArray option for embedded collections.

1<?php
#[Document]
class User
{
    // ...

    /** @var Collection<PhoneNumber> */
    #[EmbedMany(targetDocument: PhoneNumber::class, storeEmptyArray: true)]
    private Collection $phoneNumbers;
    // ...
}


2


3


4


5


6


7


8


9


10


11

Now, when the $phoneNumbers collection is empty, an empty array will be stored in the database for the User document's embedded phoneNumbers collection, even if there are no actual embedded documents in the collection.