You are browsing a version that is no longer maintained.

Embedded Mapping

This chapter explains how embedded documents are mapped in Doctrine.

Embed One

Embed a single document:

PHP

1 <?php

/** @Document */
class User
{
    // ...

    /** @EmbedOne(targetDocument="Address") */
    private $address;

    // ...
}

/** @EmbeddedDocument */
class Address
{
    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

XML

1 <?xml version="1.0" encoding="UTF-8"?>
<doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
                http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
  <document name="Documents\User">
        <embed-one field="address" target-document="Address" />
  </document>
</doctrine-mongo-mapping>
2
3
4
5
6
7
8
9

YAML

1 User:
  type: document
  embedOne:
    address:
      targetDocument: Address

Address:
  type: embeddedDocument
2
3
4
5
6
7
8

Embed Many

Embed many documents:

PHP

1 <?php

use Doctrine\Common\Collections\ArrayCollection;

/** @Document */
class User
{
    // ...

    /** @EmbedMany(targetDocument="Phonenumber") */
    private $phonenumbers;

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

/** @EmbeddedDocument */
class Phonenumber
{
    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

XML

1 <?xml version="1.0" encoding="UTF-8"?>
<doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping
                http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd">
  <document name="Documents\User">
        <embed-many field="phonenumbers" target-document="Phonenumber" />
  </document>
</doctrine-mongo-mapping>
2
3
4
5
6
7
8
9

YAML

1 User:
  type: document
  embedMany:
    phonenumbers:
      targetDocument: Phonenumber

Phonenumber:
  type: embeddedDocument
2
3
4
5
6
7
8

Mixing Document Types

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

PHP

1 <?php

use Doctrine\Common\Collections\ArrayCollection;

/** @Document */
class User
{
    // ..

    /** @EmbedMany */
    private $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

XML
```
1 <embed-many field="tasks" />
```
YAML
```
1 embedMany:
  tasks: ~
2
```

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:

PHP

1 <?php

use Doctrine\Common\Collections\ArrayCollection;

/** @Document */
class User
{
    // ..

    /**
     * @EmbedMany(discriminatorField="type")
     */
    private $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

XML

1 <embed-many field="tasks">
    <discriminator-field name="type" />
</embed-many>
2
3

YAML

1 embedMany:
  tasks:
    discriminatorField: type
2
3

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

PHP

1 <?php

use Doctrine\Common\Collections\ArrayCollection;

/** @Document */
class User
{
    // ..

    /**
     * @EmbedMany(
     *   discriminatorMap={
     *     "download"="DownloadTask",
     *     "build"="BuildTask"
     *   }
     * )
     */
    private $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
24
25

XML

1 <embed-many field="tasks">
    <discriminator-map>
        <discriminator-mapping value="download" class="DownloadTask" />
        <discriminator-mapping value="build" class="BuildTask" />
    </discriminator-map>
</embed-many>
2
3
4
5
6

YAML

1 embedMany:
  tasks:
    discriminatorMap:
      download: DownloadTask
      build: BuildTask
2
3
4
5

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:

PHP

1 <?php

/** @Document */
class User
{
    // ..

    /**
     * @EmbedMany(
     *   discriminatorMap={
     *     "download"="DownloadTask",
     *     "build"="BuildTask"
     *   },
     *   defaultDiscriminatorValue="download"
     * )
     */
    private $tasks = array();

    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

XML

1 <embed-many field="tasks">
    <discriminator-map>
        <discriminator-mapping value="download" class="DownloadTask" />
        <discriminator-mapping value="build" class="BuildTask" />
    </discriminator-map>
    <default-discriminator-value value="download" />
</embed-many>
2
3
4
5
6
7

YAML

1 embedMany:
  tasks:
    discriminatorMap:
      download: DownloadTask
      build: BuildTask
    defaultDiscriminatorValue: download
2
3
4
5
6

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.

1	<?php /** @Document / class User { // ... /* @EmbedOne(targetDocument="Address") / private $address; // ... } /* @EmbeddedDocument */ class Address { // ... }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

1	<?xml version="1.0" encoding="UTF-8"?> <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd"> <document name="Documents\User"> <embed-one field="address" target-document="Address" /> </document> </doctrine-mongo-mapping>
2
3
4
5
6
7
8
9

1	User: type: document embedOne: address: targetDocument: Address Address: type: embeddedDocument
2
3
4
5
6
7
8

1	<?php use Doctrine\Common\Collections\ArrayCollection; /** @Document / class User { // ... /* @EmbedMany(targetDocument="Phonenumber") / private $phonenumbers; // ... public function __construct() { $this->phonenumbers = new ArrayCollection(); } } /* @EmbeddedDocument */ class Phonenumber { // ... }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1	User: type: document embedMany: phonenumbers: targetDocument: Phonenumber Phonenumber: type: embeddedDocument
2
3
4
5
6
7
8

1	<embed-many field="tasks"> <discriminator-field name="type" /> </embed-many>
2
3

1	embedMany: tasks: discriminatorMap: download: DownloadTask build: BuildTask
2
3
4
5

Maintained

Unmaintained

Embedded Mapping

Embed One

Embed Many

Mixing Document Types

Cascading Operations