Basic Mapping

Mapping Drivers

Doctrine provides several different ways for specifying object document mapping metadata:

• Attributes
• XML
• Raw PHP Code

Introduction to Attributes

PHP attributes are a PHP 8+ feature that provides a native way to add metadata to classes, methods, properties, and other language constructs. They replace doctrine annotations by offering a standardized approach to metadata, eliminating the need for the separate parsing library required by annotations.

In this documentation we follow the PER Coding Style for attributes. We use named arguments for attributes as they argument names or attribute classes constructors are covered by Doctrine Backward-Compatibility promise.

Persistent classes

In order to mark a class for object-relational persistence it needs to be designated as a document. This can be done through the #[Document] marker attribute.

By default, the document will be persisted to a database named doctrine and a collection with the same name as the class name. In order to change that, you can use the db and collection option as follows:

Now instances of Documents\User will be persisted into a collection named users in the database my_db.

If you want to omit the db attribute you can configure the default db to use with the setDefaultDB method:

1
<?php

$config->setDefaultDB('my_db');
2
3

Doctrine Mapping Types

A Doctrine Mapping Type defines the mapping between a PHP type and a MongoDB type. You can even write your own custom mapping types.

Here is a quick overview of the built-in mapping types:

• bin
• bin_bytearray
• bin_custom
• bin_func
• bin_md5
• bin_uuid
• bool
• collection
• custom_id
• date
• date_immutable
• decimal128
• file
• float
• hash
• id
• int
• key
• object_id
• raw
• string
• timestamp

You can read more about the available MongoDB types on php.net.

Generally, the name of each built-in mapping type hints as to how the value will be converted. This list explains some of the less obvious mapping types:

• bin: string to MongoDBBSONBinary instance with a "generic" type (default)
• bin_bytearray: string to MongoDBBSONBinary instance with a "byte array" type
• bin_custom: string to MongoDBBSONBinary instance with a "custom" type
• bin_func: string to MongoDBBSONBinary instance with a "function" type
• bin_md5: string to MongoDBBSONBinary instance with a "md5" type
• bin_uuid: string to MongoDBBSONBinary instance with a "uuid" type
• collection: numerically indexed array to MongoDB array
• date: DateTime to MongoDB\BSON\UTCDateTime
• date_immutable: DateTimeImmutable to MongoDB\BSON\UTCDateTime
• decimal128: string to MongoDB\BSON\Decimal128, requires ext-bcmath
• hash: associative array to MongoDB object
• id: string to ObjectId by default, but other formats are possible
• timestamp: string to MongoDB\BSON\Timestamp
• raw: any type

Property Mapping

After a class has been marked as a document it can specify mappings for its instance fields. Here we will only look at simple fields that hold scalar values like strings, numbers, etc. References to other objects and embedded objects are covered in the chapter Reference Mapping.

1
<?php

//...

$document = new MyPersistentClass();
$document->setId('my_unique_identifier');
$dm->persist($document);
$dm->flush();
2
3
4
5
6
7
8

1
<?php

//...

$document = $dm->find(MyPersistentClass::class, 'my_unique_identifier');
2
3
4
5

1
<?php

namespace Vendor\Specific;

use Doctrine\ODM\MongoDB\DocumentManager;
use Doctrine\ODM\MongoDB\Id\IdGenerator;

class Generator implements IdGenerator
{
    public function generate(DocumentManager $dm, object $document)
    {
        // Your own logic here
        return 'my_generated_id';
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Multiple Document Types in a Collection

You can easily store multiple types of documents in a single collection. This requires specifying the same collection name, discriminatorField, and (optionally) discriminatorMap mapping options for each class that will share the collection. Here is an example:

1
<?php

#[Document(collection: 'my_documents')]
#[DiscriminatorField('type')]
#[DiscriminatorMap(['article' => Article::class, 'album' => Album::class])]
class Article
{
    // ...
}

#[Document(collection: 'my_documents')]
#[DiscriminatorField('type')]
#[DiscriminatorMap(['article' => Article::class, 'album' => Album::class])]
class Album
{
    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

All instances of Article and Album will be stored in the my_documents collection. You can query for the documents of a particular class just like you normally would and the results will automatically be limited based on the discriminator value for that class.

If you wish to query for multiple types of documents from the collection, you may pass an array of document class names when creating a query builder:

1
<?php

$query = $dm->createQuery([Article::class, Album::class]);
$documents = $query->execute();
2
3
4

The above will return a cursor that will allow you to iterate over all Article and Album documents in the collections.