You are browsing a version that has not yet been released.

Attributes Reference

In this chapter a reference of every Doctrine ODM Attribute is given with short explanations on their context and usage.

#[AlsoLoad]

Specify one or more MongoDB fields to use for loading data if the original field does not exist.

1 <?php

class User
{
    #[Field(type: 'string')]
    #[AlsoLoad('name')]
    public string $fullName;
}
2
3
4
5
6
7
8

The $fullName property will be loaded from fullName if it exists, but fall back to name if it does not exist. If multiple fall back fields are specified, ODM will consider them in order until the first is found.

Additionally, #[AlsoLoad] may annotate a method with one or more field names. Before normal hydration, the field(s) will be considered in order and the method will be invoked with the first value found as its single argument.

1 <?php

class User
{
    #[AlsoLoad(['name', 'fullName'])]
    public function populateFirstAndLastName(string $name): void
    {
        list($this->firstName, $this->lastName) = explode(' ', $name);
    }
}
2
3
4
5
6
7
8
9
10

For additional information on using #[AlsoLoad], see Migrations.

#[ChangeTrackingPolicy]

This attribute is used to change the change tracking policy for a document:

1 <?php

#[Document]
#[ChangeTrackingPolicy('DEFERRED_EXPLICIT')]
class Person
{
    // ...
}
2
3
4
5
6
7
8

For a list of available policies, read the section on change tracking policies.

#[DefaultDiscriminatorValue]

This attribute can be used when using #[DiscriminatorField]. It will be used as a fallback value if a document has no discriminator field set. This must correspond to a value from the configured discriminator map.

1 <?php

#[Document]
#[InheritanceType('SINGLE_COLLECTION')]
#[DiscriminatorField('type')]
#[DiscriminatorMap(['person' => Person::class, 'employee' => Employee::class])]
#[DefaultDiscriminatorValue('person')]
class Person
{
    // ...
}
2
3
4
5
6
7
8
9
10
11

#[DiscriminatorField]

This attribute is required for the top-most class in a single collection inheritance hierarchy. It takes a string as its only argument, which specifies the database field to store a class name or key (if a discriminator map is used). ODM uses this field during hydration to select the instantiation class.

1 <?php

#[Document]
#[InheritanceType("SINGLE_COLLECTION")]
#[DiscriminatorField("type")]
class SuperUser
{
    // ...
}
2
3
4
5
6
7
8
9

For backwards compatibility, the discriminator field may also be specified via either the name or fieldName attribute.

#[DiscriminatorMap]

This attribute is required for the top-most class in a single collection inheritance hierarchy. It takes an array as its only argument, which maps keys to class names. The class names must be fully qualified. Using the ::class constant is supported. When a document is persisted to the database, its class name key will be stored in the discriminator field instead of the FQCN . If the discriminator map is non-empty and it does not contain the class name of the persisted document, a \Doctrine\ODM\MongoDB\Mapping\MappingException will be thrown.

1 <?php

#[Document]
#[InheritanceType('SINGLE_COLLECTION')]
#[DiscriminatorField('type')]
#[DiscriminatorMap(['person' => Person::class, 'employee' => Employee::class])]
class Person
{
    // ...
}
2
3
4
5
6
7
8
9
10

#[Document]

Required attribute to mark a PHP class as a document, whose persistence will be managed by ODM.

Optional attributes:

db - By default, the document manager will use the MongoDB database defined in the configuration, but this option may be used to override the database for a particular document class.
collection - By default, the collection name is derived from the document's class name, but this option may be used to override that behavior.
repositoryClass - Specifies a custom repository class to use.
readOnly - Prevents document from being updated: it can only be inserted, upserted or removed.
writeConcern - Specifies the write concern for this document that overwrites the default write concern specified in the configuration. It does not overwrite a write concern given as option to the flush method when committing your documents.

1 <?php

#[Document(
    db: 'documents',
    collection: 'users',
    repositoryClass: MyProject\UserRepository::class,
    indexes: [
        new Index(keys: ['username' => 'desc'], options: ['unique' => true])
    ],
    readOnly: true,
)]
class User
{
    //...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15

#[EmbedMany]

This attribute is similar to #[EmbedOne], but instead of embedding one document, it embeds a collection of documents.

Optional attributes:

targetDocument - A FQCN of the target document.
discriminatorField - The database field name to store the discriminator value within the embedded document.
discriminatorMap - Map of discriminator values to class names.
defaultDiscriminatorValue - A default value for discriminatorField if no value has been set in the embedded document.
strategy - The strategy used to persist changes to the collection. Possible values are addToSet, pushAll, set, and setArray. pushAll is the default. See Storage Strategies for more information.
collectionClass - A FQCN of class that implements Collection interface and is used to hold documents. When typed properties are used it is inherited from PHP type, otherwise Doctrine's ArrayCollection is used by default.
notSaved - The property is loaded if it exists in the database; however, ODM will not save the property value back to the database.

1 <?php

class User
{
    /** @var Collection<BookTag|SongTag> */
    #[EmbedMany(
        strategy:'set',
        discriminatorField:'type',
        discriminatorMap: [
            'book' => Documents\BookTag::class,
            'song' => Documents\SongTag::class,
        ],
        defaultDiscriminatorValue: 'book',
    )]
    private Collection $tags;
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Depending on the embedded document's class, a value of user or author will be stored in the type field and used to reconstruct the proper class during hydration. The type field need not be mapped on the embedded document classes.

#[EmbedOne]

The #[EmbedOne] attribute works similarly to #[ReferenceOne], except that that document will be embedded within the parent document. Consider the following excerpt from the MongoDB documentation:

The key question in MongoDB schema design is does this object merit its own collection, or rather should it be embedded within objects in other collections? In relational databases, each sub-item of interest typically becomes a separate table (unless you are denormalizing for performance). In MongoDB, this is not recommended – embedding objects is much more efficient. Data is then collocated on disk; client-server turnarounds to the database are eliminated. So in general, the question to ask is, why would I not want to embed this object?

Optional attributes:

targetDocument - A FQCN of the target document. When typed properties are used it is inherited from PHP type.
discriminatorField - The database field name to store the discriminator value within the embedded document.
discriminatorMap - Map of discriminator values to class names.
defaultDiscriminatorValue - A default value for discriminatorField if no value has been set in the embedded document.
notSaved - The property is loaded if it exists in the database; however, ODM will not save the property value back to the database.

1 <?php

class Thing
{
    #[EmbedOne(
         discriminatorField: 'type',
         discriminatorMap: [
             'user' => Documents\User::class,
             'author' => Documents\Author::class,
         ],
         defaultDiscriminatorValue: 'user',
    )]
    private User|Author $creator;
}
2
3
4
5
6
7
8
9
10
11
12
13
14

#[EmbeddedDocument]

Marks the document as embeddable. This attribute is required for any documents to be stored within an #[EmbedOne], #[EmbedMany] or #[File\\Metadata] relationship.

1 <?php

#[EmbeddedDocument]
class Money
{
    #[Field(type: 'float')]
    private float $amount;

    public function __construct(float $amount)
    {
        $this->amount = $amount;
    }
    //...
}

#[Document(db: 'finance', collection: 'wallets')]
class Wallet
{
    #[EmbedOne(targetDocument: Money::class)]
    private Money $money;

    public function setMoney(Money $money): void
    {
        $this->money = $money;
    }
    //...
}
//...
$wallet = new Wallet();
$wallet->setMoney(new Money(34.39));
$dm->persist($wallet);
$dm->flush();
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

Unlike normal documents, embedded documents cannot specify their own database or collection. That said, a single embedded document class may be used with multiple document classes, and even other embedded documents!

#[Field]

Marks an annotated instance variable for persistence. Values for this field will be saved to and loaded from the document store as part of the document class' lifecycle.

Optional attributes:

type - Name of the ODM type, which will determine the value's representation in PHP and BSON (i.e. MongoDB). See Basic Mapping for a list of types. Defaults to "string" or Type from PHP property type.
enumType - A FQCN of an enum. ODM will automatically handle conversion from the backing value stored in the database to an enum. Can be auto-detected by type from PHP property type.
name - By default, the property name is used for the field name in MongoDB; however, this option may be used to specify a database field name.
nullable - By default, ODM will $unset fields in MongoDB if the PHP value is null. Specify true for this option to force ODM to store a null value in the database instead of unsetting the field.
notSaved - The property is loaded if it exists in the database; however, ODM will not save the property value back to the database.

Examples:

1 <?php

#[Document]
class User
{
    #[Field(type: 'string')]
    protected string $username;

    #[Field(type: 'string', name: 'co')]
    protected string $country;

    #[Field(type: 'float')]
    protected float $height;
}
2
3
4
5
6
7
8
9
10
11
12
13
14

#[File]

This marks the document as a GridFS file. GridFS allow storing larger amounts of data than regular documents.

Optional attributes:

db - By default, the document manager will use the MongoDB database defined in the configuration, but this option may be used to override the database for a particular file.
bucketName - By default, files are stored in a bucket called fs. You can customize that bucket name with this property.
repositoryClass - Specifies a custom repository class to use. The class must extend the Doctrine\ODM\MongoDB\Repository\GridFSRepository interface.
readOnly - Prevents the file from being updated: it can only be inserted, upserted or removed.
writeConcern - Specifies the write concern for this file that overwrites the default write concern specified in the configuration.

#[FileChunkSize]

This maps the chunkSize property of a GridFS file to a property. It contains the size of a single file chunk in bytes. No other options can be set.

#[FileFilename]

This maps the filename property of a GridFS file to a property. No other options can be set.

#[FileLength]

This maps the length property of a GridFS file to a property. It contains the size of the entire file in bytes. No other options can be set.

#[FileMetadata]

This maps the metadata property of a GridFS file to a property. Metadata can be used to store additional properties in a file. The metadata document must be an embedded document mapped using #[EmbeddedDocument].

Optional attributes:

targetDocument - A FQCN of the target document.
discriminatorField - The database field name to store the discriminator value within the embedded document.
discriminatorMap - Map of discriminator values to class names.
defaultDiscriminatorValue - A default value for discriminatorField if no value has been set in the embedded document.

#[FileUploadDate]

This maps the uploadDate property of a GridFS file to a property. No other options can be set.

#[HasLifecycleCallbacks]

This attribute must be set on the document class to instruct Doctrine to check for lifecycle callback attributes on public methods. Using #[PreFlush], #[PreLoad], #[PostLoad], #[PrePersist], #[PostPersist], #[PreRemove], #[PostRemove], #[PreUpdate], or #[PostUpdate] on methods without this attribute will cause Doctrine to ignore the callbacks.

1 <?php

#[Document]
#[HasLifecycleCallbacks]
class User
{
    #[PostPersist]
    public function sendWelcomeEmail(): void {}
}
2
3
4
5
6
7
8
9

#[Id]

The annotated instance variable will be marked as the document identifier. The default behavior is to store an MongoDB\BSON\ObjectId instance, but you may customize this via the strategy attribute.

1 <?php

#[Document]
class User
{
    #[Id]
    protected string $id;
}
2
3
4
5
6
7
8

The property annotated with #[Id] cannot be readonly even if the value is set only once and should never be updated. This is because the property is set outside of the scope of the class, which is not allowed in PHP for readonly properties.

#[Index]

This attribute is used to specify indexes to be created on the collection (or embedding document's collection in the case of #[EmbeddedDocument]). It may also be used at the property-level to define single-field indexes.

Optional attributes:

keys - Mapping of indexed fields to their ordering or index type. ODM will allow asc and desc to be used in place of 1 and -1, respectively. Special index types (e.g. 2dsphere) should be specified as strings. This is required when #[Index] is used at the class level.
options - Options for creating the index. Options are documented in the indexes chapter.

The keys and options attributes correspond to the arguments for MongoDB\Collection::createIndex(). ODM allows mapped field names (i.e. PHP property names) to be used when defining keys.

1 <?php

#[Document]
#[Index(keys: ['username' => 'desc' ], options: ['unique' => true])]
class User
{
    //...
}
2
3
4
5
6
7
8

If you are creating a single-field index, you can simply specify an #[Index] or #[UniqueIndex] on a mapped property:

1 <?php

#[Document]
class User
{
    #[Field(type: 'string')]
    #[UniqueIndex]
    private string $username;
}
2
3
4
5
6
7
8
9

If the name option is specified on an index in an embedded document, it will be prefixed with the embedded field path before creating the index. This is necessary to avoid index name conflict when the same document is embedded multiple times in a single collection. Prefixing of the index name can cause errors due to excessive index name length. In this case, try shortening the index name or embedded field path.

#[Indexes]

The #[Indexes] attribute was deprecated in 2.2 and will be removed in 3.0. Please move all nested new Index instances to a class level attributes.

This attribute may be used at the class level to specify an array of #[Index] attributes. It is functionally equivalent to specifying multiple #[Index] attributes on a class level.

1 <?php

#[Document]
#[Indexes([
    new Index(keys: ['username' => 'desc'], options: ['unique' => true]),
])]
class User
{
    //...
}
2
3
4
5
6
7
8
9
10

#[InheritanceType]

This attribute must appear on the top-most class in an inheritance hierarchy. SINGLE_COLLECTION and COLLECTION_PER_CLASS are currently supported.

Examples:

1 <?php

#[Document]
#[InheritanceType('COLLECTION_PER_CLASS')]
class Person
{
    // ...
}

#[Document]
#[InheritanceType('SINGLE_COLLECTION')]
#[DiscriminatorField('type')]
#[DiscriminatorMap(['person' => Person::class, 'employee' => Employee::class])]
class Person
{
    // ...
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

#[Lock]

The annotated instance variable will be used to store lock information for pessimistic locking. This is only compatible with the int type, and cannot be combined with #[Id].

1 <?php

#[Document]
class Thing
{
    #[Field(type: 'int')]
    #[Lock]
    private int $lock;
}
2
3
4
5
6
7
8
9

#[MappedSuperclass]

The attribute is used to specify classes that are parents of document classes and should not be managed directly. See inheritance mapping for additional information.

1 <?php

#[MappedSuperclass]
class BaseDocument
{
    // ...
}
2
3
4
5
6
7

#[PostLoad]

Marks a method on the document class to be called on the postLoad event. The #[HasLifecycleCallbacks] attribute must be present on the same class for the method to be registered.

1 <?php

#[Document]
#[HasLifecycleCallbacks]
class Article
{
    // ...

    #[PostLoad]
    public function postLoad(): void
    {
        // ...
    }
}
2
3
4
5
6
7
8
9
10
11
12
13
14