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
    1User: type: document embedOne: address: targetDocument: Address Address: type: embeddedDocument
    2
    3
    4
    5
    6
    7
    8

Embed Many

Embed many documents:

  • PHP
    1<?php /** @Document */ class User { // ... /** @EmbedMany(targetDocument="Phonenumber") */ private $phonenumbers = array(); // ... } /** @EmbeddedDocument */ class Phonenumber { // ... }
    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-many field="phonenumbers" target-document="Phonenumber" /> </document> </doctrine-mongo-mapping>
    2
    3
    4
    5
    6
    7
    8
    9
  • YAML
    1User: 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 /** @Document */ class User { // .. /** @EmbedMany */ private $tasks = array(); // ... }
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
  • XML
    1<embed-many field="tasks" />
  • YAML
    1embedMany: 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 /** @Document */ class User { // .. /** * @EmbedMany(discriminatorField="type") */ private $tasks = array(); // ... }
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
  • XML
    1<embed-many fieldName="tasks"> <discriminator-field name="type" /> </embed-many>
    2
    3
  • YAML
    1embedMany: tasks: discriminatorField: type
    2
    3

You can also specify a discriminator map to avoid storing the fully qualified class name in each embedded document:

  • PHP
    1<?php /** @Document */ class User { // .. /** * @EmbedMany( * discriminatorMap={ * "download"="DownloadTask", * "build"="BuildTask" * } * ) */ private $tasks = array(); // ... }
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
  • XML
    1<embed-many fieldName="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
    1embedMany: 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 fieldName="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
    1embedMany: 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.