This chapter explains how references between documents are mapped with Doctrine.
Examples of many-valued references in this manual make use of a
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
which incorporates change-tracking functionality; however, this class is
constructed internally during hydration. As a developer, you should develop with
Collection interface in mind so that your code can operate with any
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.
ArrayAccess), and even a concrete implementation in
objects cannot always be used everywhere that a native array is accepted.
Collection interface and
ArrayCollection implementation are
conceptually very similar to
ArrayObject, with some slight differences and
Reference one document:
Reference many documents:
Mixing Document Types
If you want to store different types of documents in references, you can simply
$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 MongoDB shell tends to ignore fields other than
when displaying DBRef objects. You can verify the presence of any
and discriminator fields by querying and examining the document with a
driver. See SERVER-10777
for additional discussion on this issue.
The name of the field within the DBRef object can be customized via the
You can also specify a discriminator map to avoid storing the fully qualified class name in each DBRef object:
If you have references without a discriminator value that should be considered a certain class, you can optionally specify a default discriminator value:
By default all references are stored as a DBRef object with the traditional
$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.
profile field will only store the
MongoId of the referenced
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.
By default, Doctrine will not cascade any
UnitOfWork operations to
referenced documents. You must explicitly enable this functionality:
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.