Reference Mapping

Collections

Examples of many-valued references in this manual make use of a Collection interface and a corresponding ArrayCollection implementation, which are defined in the Doctrine\Common\Collections namespace. These classes have no dependencies on ODM, and can therefore be used within your domain model and elsewhere without introducing coupling to the persistence layer.

ODM also provides a PersistentCollection implementation of Collection, which incorporates change-tracking functionality; however, this class is constructed internally during hydration. As a developer, you should develop with the Collection interface in mind so that your code can operate with any implementation.

Why are these classes used over PHP arrays? Native arrays cannot be transparently extended in PHP, which is necessary for many advanced features provided by the ODM. Although PHP does provide various interfaces that allow objects to operate like arrays (e.g. Traversable, Countable, ArrayAccess), and even a concrete implementation in ArrayObject, these objects cannot always be used everywhere that a native array is accepted. Doctrine's Collection interface and ArrayCollection implementation are conceptually very similar to ArrayObject, with some slight differences and improvements.

Reference One

Reference one document:

1
<?php

/** @Document */
class Product
{
    // ...

    /**
     * @ReferenceOne(targetDocument="Shipping")
     */
    private $shipping;

    // ...
}

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

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\Product">
        <reference-one field="shipping" target-document="Documents\Shipping" />
  </document>
</doctrine-mongo-mapping>
2
3
4
5
6
7
8
9

1
User:
  type: document
  referenceOne:
    shipping:
      targetDocument: Documents\Shipping
2
3
4
5

Reference Many

Reference many documents:

1
<?php

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

    /**
     * @ReferenceMany(targetDocument="Account")
     */
    private $accounts = array();

    // ...
}

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

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\Product">
        <reference-many field="accounts" target-document="Documents\Account" />
  </document>
</doctrine-mongo-mapping>
2
3
4
5
6
7
8
9

1
User:
  type: document
  referenceMany:
    accounts:
      targetDocument: Documents\Account
2
3
4
5

Mixing Document Types

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

1
<?php

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

    /** @ReferenceMany */
    private $favorites = array();

    // ...
}
2
3
4
5
6
7
8
9
10
11
12

1
<field fieldName="favorites" />

1
referenceMany:
    favorites: ~
2

Now the $favorites property can store a reference to any type of document! The class name will be automatically stored in a field named _doctrine_class_name within the DBRef object.

The name of the field within the DBRef object can be customized via the discriminatorField option:

1
<?php

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

    /**
     * @ReferenceMany(discriminatorField="type")
     */
    private $favorites = array();

    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14

1
<reference-many fieldName="favorites">
    <discriminator-field name="type" />
</reference-many>
2
3

1
referenceMany:
  favorites:
    discriminatorField: type
2
3

You can also specify a discriminator map to avoid storing the FQCN in each DBRef object:

1
<?php

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

    /**
     * @ReferenceMany(
     *   discriminatorMap={
     *     "album"="Album",
     *     "song"="Song"
     *   }
     * )
     */
    private $favorites = array();

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

1
<reference-many fieldName="favorites">
    <discriminator-map>
        <discriminator-mapping value="album" class="Documents\Album" />
        <discriminator-mapping value="song" class="Documents\Song" />
    </discriminator-map>
</reference-many>
2
3
4
5
6

1
referenceMany:
  favorites:
    discriminatorMap:
      album: Documents\Album
      song: Documents\Song
2
3
4
5

If you have references without a discriminator value that should be considered a certain class, you can optionally specify a default discriminator value:

1
<?php

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

    /**
     * @ReferenceMany(
     *   discriminatorMap={
     *     "album"="Album",
     *     "song"="Song"
     *   },
     *   defaultDiscriminatorValue="album"
     * )
     */
    private $favorites = array();

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

1
<reference-many fieldName="favorites">
    <discriminator-map>
        <discriminator-mapping value="album" class="Documents\Album" />
        <discriminator-mapping value="song" class="Documents\Song" />
    </discriminator-map>
    <default-discriminator-value value="album" />
</reference-many>
2
3
4
5
6
7

1
referenceMany:
  favorites:
    discriminatorMap:
      album: Documents\Album
      song: Documents\Song
    defaultDiscriminatorValue: album
2
3
4
5
6

Storing References

By default all references are stored as a DBRef object with the traditional $ref, $id, and (optionally) $db fields (in that order). For references to documents of a single collection, storing the collection (and database) names for each reference may be redundant. You can use simple references to store the referenced document's identifier (e.g. MongoId) instead of a DBRef.

Example:

1
<?php

/**
 * @ReferenceOne(targetDocument="Profile", storeAs="id")
 */
private $profile;
2
3
4
5
6

1
<reference-one target-document="Documents\Profile", store-as="id" />

1
referenceOne:
  profile:
    storeAs: id
2
3

Now, the profile field will only store the MongoId of the referenced Profile document.

Simple references reduce the amount of storage used, both for the document itself and any indexes on the reference field; however, simple references cannot be used with discriminators, since there is no DBRef object in which to store a discriminator value.

In addition to saving references as DBRef with $ref, $id, and $db fields and as MongoId, it is possible to save references as DBRef without the $db field. This solves problems when the database name changes (and also reduces the amount of storage used).

The storeAs option has three possible values:

• dbRefWithDb: Uses a DBRef with $ref, $id, and $db fields (this is the default)
• dbRef: Uses a DBRef with $ref and $id
• id: Uses a MongoId

Cascading Operations

By default, Doctrine will not cascade any UnitOfWork operations to referenced documents. You must explicitly enable this functionality:

1
<?php

/**
 * @ReferenceOne(targetDocument="Profile", cascade={"persist"})
 */
private $profile;
2
3
4
5
6

1
<reference-one target-document="Documents\Profile">
    <cascade>
        <persist/>
    </cascade>
</reference-one>
2
3
4
5

1
referenceOne:
  profile:
    cascade: [persist]
2
3

The valid values are:

• all - cascade all operations by default.
• detach - cascade detach operation to referenced documents.
• merge - cascade merge operation to referenced documents.
• refresh - cascade refresh operation to referenced documents.
• remove - cascade remove operation to referenced documents.
• persist - cascade persist operation to referenced documents.

Orphan Removal

There is another concept of cascading that is relevant only when removing documents from collections. If a Document of type A contains references to privately owned Documents B then if the reference from A to B is removed the document B should also be removed, because it is not used anymore.

OrphanRemoval works with both reference one and many mapped fields.

As a better example consider an Addressbook application where you have Contacts, Addresses and StandingData:

1
<?php

namespace Addressbook;

use Doctrine\Common\Collections\ArrayCollection;

/**
 * @Document
 */
class Contact
{
    /** @Id */
    private $id;

    /** @ReferenceOne(targetDocument="StandingData", orphanRemoval=true) */
    private $standingData;

    /** @ReferenceMany(targetDocument="Address", mappedBy="contact", orphanRemoval=true) */
    private $addresses;

    public function __construct()
    {
        $this->addresses = new ArrayCollection();
    }

    public function newStandingData(StandingData $sd)
    {
        $this->standingData = $sd;
    }

    public function removeAddress($pos)
    {
        unset($this->addresses[$pos]);
    }
}
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
35

Now two examples of what happens when you remove the references:

1
<?php

$contact = $dm->find("Addressbook\Contact", $contactId);
$contact->newStandingData(new StandingData("Firstname", "Lastname", "Street"));
$contact->removeAddress(1);

$dm->flush();
2
3
4
5
6
7

In this case you have not only changed the Contact document itself but you have also removed the references for standing data and as well as one address reference. When flush is called not only are the references removed but both the old standing data and the one address documents are also deleted from the database.