Embedded Mapping

This chapter explains how embedded documents are mapped in Doctrine.

Embed One

Embed a single document:

  • PHP
    <?php
    
    /** @Document */
    class User
    {
        // ...
    
        /** @EmbedOne(targetDocument="Address") */
        private $address;
    
        // ...
    }
    
    /** @EmbeddedDocument */
    class Address
    {
        // ...
    }
    
  • XML
    <?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>
    

Embed Many

Embed many documents:

  • PHP
    <?php
    
    /** @Document */
    class User
    {
        // ...
    
        /** @EmbedMany(targetDocument="Phonenumber") */
        private $phonenumbers = array();
    
        // ...
    }
    
    /** @EmbeddedDocument */
    class Phonenumber
    {
        // ...
    }
    
  • XML
    <?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>
    

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
    <?php
    
    /** @Document */
    class User
    {
        // ..
    
        /** @EmbedMany */
        private $tasks = array();
    
        // ...
    }
    
  • XML
    <embed-many field="tasks" />
    

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
    <?php
    
    /** @Document */
    class User
    {
        // ..
    
        /**
         * @EmbedMany(discriminatorField="type")
         */
        private $tasks = array();
    
        // ...
    }
    
  • XML
    <embed-many field="tasks">
        <discriminator-field name="type" />
    </embed-many>
    

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

  • PHP
    <?php
    
    /** @Document */
    class User
    {
        // ..
    
        /**
         * @EmbedMany(
         *   discriminatorMap={
         *     "download"="DownloadTask",
         *     "build"="BuildTask"
         *   }
         * )
         */
        private $tasks = array();
    
        // ...
    }
    
  • XML
    <embed-many field="tasks">
        <discriminator-map>
            <discriminator-mapping value="download" class="DownloadTask" />
            <discriminator-mapping value="build" class="BuildTask" />
        </discriminator-map>
    </embed-many>
    

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
    <?php
    
    /** @Document */
    class User
    {
        // ..
    
        /**
         * @EmbedMany(
         *   discriminatorMap={
         *     "download"="DownloadTask",
         *     "build"="BuildTask"
         *   },
         *   defaultDiscriminatorValue="download"
         * )
         */
        private $tasks = array();
    
        // ...
    }
    
  • XML
    <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>
    

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.

Fork me on GitHub