will/mongodb-odm-docs-dash
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
897a334bf6
mongodb-odm-docs-dash/build.docset/Contents/Resources/Documents/reference/annotations-reference.html
Will Bradley 897a334bf6 Initial commit
2017-12-01 19:35:11 -08:00

1459 lines
87 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Annotations Reference &mdash; Doctrine MongoDB ODM 1.1.5 documentation</title>
<link rel="stylesheet" href="../_static/bootstrap/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/layout.css" type="text/css" />
<link rel="stylesheet" href="../_static/configurationblock.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.5',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/configurationblock.js"></script>
<script src="../_static/bootstrap/js/bootstrap.min.js"></script>
<script type="text/javascript">
<!--
$(document).ready(function() {
$("#versions").change(function() {
var docsUrl = $(this).val();
window.location.href = docsUrl;
});
});
-->
</script>
<link rel="shortcut icon" href="../_static/doctrine.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="Doctrine MongoDB ODM 1.1.5 documentation" href="../index.html" />
</head>
<body>
<div id="wrapper">
<div id="header">
<h1 id="h1title"></h1>
<div id="logo">
<a href="http://www.doctrine-project.org/">Doctrine - PHP Database Libraries</a>
</div>
</div>
<div id="nav" class="cls">
<div class="tl cls">
<ul>
<li><a target="_top" href="http://www.doctrine-project.org/">Home</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/about.html">About</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/projects.html">Projects</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/contribute.html">Contribute</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/community.html">Community</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/archive.html">Blog</a></li>
<li><a target="_top" href="http://www.doctrine-project.org/jira">Development</a></li>
</ul>
</div>
</div>
<div id="content" class="cls">
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="/">Doctrine Homepage</a> &raquo;</li>
<li><a href="../index.html">Doctrine MongoDB ODM 1.1.5 documentation</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" >
<div class="section" id="annotations-reference">
<h1>Annotations Reference<a class="headerlink" href="#annotations-reference" title="Permalink to this headline"></a></h1>
<p>In this chapter a reference of every Doctrine 2 ODM Annotation is
given with short explanations on their context and usage.</p>
<div class="section" id="alsoload">
<h2>&#64;AlsoLoad<a class="headerlink" href="#alsoload" title="Permalink to this headline"></a></h2>
<p>Specify one or more MongoDB fields to use for loading data if the original field
does not exist.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @AlsoLoad(&quot;name&quot;) */</span>
<span class="k">public</span> <span class="nv">$fullName</span><span class="p">;</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">$fullName</span></code> property will be loaded from <code class="docutils literal"><span class="pre">fullName</span></code> if it exists, but
fall back to <code class="docutils literal"><span class="pre">name</span></code> if it does not exist. If multiple fall back fields are
specified, ODM will consider them in order until the first is found.</p>
<p>Additionally, <a class="reference internal" href="#alsoload">&#64;AlsoLoad</a> 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.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @AlsoLoad({&quot;name&quot;, &quot;fullName&quot;}) */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">populateFirstAndLastName</span><span class="p">(</span><span class="nv">$name</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">list</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">firstName</span><span class="p">,</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">lastName</span><span class="p">)</span> <span class="o">=</span> <span class="nb">explode</span><span class="p">(</span><span class="s1">&#39; &#39;</span><span class="p">,</span> <span class="nv">$name</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For additional information on using <a class="reference internal" href="#alsoload">&#64;AlsoLoad</a>, see
<a class="reference internal" href="migrating-schemas.html"><span class="doc">Migrations</span></a>.</p>
</div>
<div class="section" id="bin">
<h2>&#64;Bin<a class="headerlink" href="#bin" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin&quot;. Converts value to
<a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::GENERIC</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Bin */</span>
<span class="k">private</span> <span class="nv">$data</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bin&quot;.</p>
</div>
</div>
<div class="section" id="bincustom">
<h2>&#64;BinCustom<a class="headerlink" href="#bincustom" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin_custom&quot;. Converts
value to <a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::CUSTOM</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @BinCustom */</span>
<span class="k">private</span> <span class="nv">$data</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bin_custom&quot;.</p>
</div>
</div>
<div class="section" id="binfunc">
<h2>&#64;BinFunc<a class="headerlink" href="#binfunc" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin_func&quot;. Converts value to
<a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::FUNC</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @BinFunc */</span>
<span class="k">private</span> <span class="nv">$data</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bin_func&quot;.</p>
</div>
</div>
<div class="section" id="binmd5">
<h2>&#64;BinMD5<a class="headerlink" href="#binmd5" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin_md5&quot;. Converts value to
<a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::MD5</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @BinMD5 */</span>
<span class="k">private</span> <span class="nv">$password</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bin_md5&quot;.</p>
</div>
</div>
<div class="section" id="binuuid">
<h2>&#64;BinUUID<a class="headerlink" href="#binuuid" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin_uuid&quot;. Converts value to
<a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::UUID</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @BinUUID */</span>
<span class="k">private</span> <span class="nv">$uuid</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Per the <a class="reference external" href="http://bsonspec.org/spec.html">BSON specification</a>, this sub-type is deprecated in favor of the
RFC 4122 UUID sub-type. Consider using <a class="reference internal" href="#binuuidrfc4122">&#64;BinUUIDRFC4122</a> instead.</p>
</div>
</div>
<div class="section" id="binuuidrfc4122">
<h2>&#64;BinUUIDRFC4122<a class="headerlink" href="#binuuidrfc4122" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bin_uuid_rfc4122&quot;. Converts
value to <a class="reference external" href="http://php.net/manual/en/class.mongobindata.php">MongoBinData</a> with <code class="docutils literal"><span class="pre">MongoBinData::UUID_RFC4122</span></code> sub-type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @BinUUIDRFC4122 */</span>
<span class="k">private</span> <span class="nv">$uuid</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">RFC 4122 UUIDs must be 16 bytes. The PHP driver will throw an exception if
the binary data's size is invalid.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bin_uuid_rfc4122&quot;.</p>
</div>
</div>
<div class="section" id="bool">
<h2>&#64;Bool<a class="headerlink" href="#bool" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;bool&quot;. Internally it uses
exactly same logic as <a class="reference internal" href="#boolean">&#64;Boolean</a> annotation and &quot;boolean&quot; type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Bool */</span>
<span class="k">private</span> <span class="nv">$active</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated because it uses a keyword that was reserved in
PHP 7. It will be removed in ODM 2.0. Please use the <a class="reference internal" href="#field">&#64;Field</a> annotation
with type &quot;bool&quot;.</p>
</div>
</div>
<div class="section" id="boolean">
<h2>&#64;Boolean<a class="headerlink" href="#boolean" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;boolean&quot;.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Boolean */</span>
<span class="k">private</span> <span class="nv">$active</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;bool&quot;.</p>
</div>
</div>
<div class="section" id="changetrackingpolicy">
<h2>&#64;ChangeTrackingPolicy<a class="headerlink" href="#changetrackingpolicy" title="Permalink to this headline"></a></h2>
<p>This annotation is used to change the change tracking policy for a document:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @ChangeTrackingPolicy(&quot;DEFERRED_EXPLICIT&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Person</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For a list of available policies, read the section on <a class="reference internal" href="change-tracking-policies.html#change-tracking-policies"><span class="std std-ref">change tracking policies</span></a>.</p>
</div>
<div class="section" id="collection">
<h2>&#64;Collection<a class="headerlink" href="#collection" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;collection&quot;. Stores and
retrieves the value as a numerically indexed array.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Collection */</span>
<span class="k">private</span> <span class="nv">$tags</span> <span class="o">=</span> <span class="k">array</span><span class="p">();</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;collection&quot;.</p>
</div>
</div>
<div class="section" id="date">
<h2>&#64;Date<a class="headerlink" href="#date" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;date&quot;. Values of any type
(e.g. integer, string, DateTime) will be converted to <a class="reference external" href="http://php.net/manual/en/class.mongodate.php">MongoDate</a> for storage
in MongoDB. The property will be a DateTime when loaded from the database.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Date */</span>
<span class="k">private</span> <span class="nv">$createdAt</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;date&quot;.</p>
</div>
</div>
<div class="section" id="defaultdiscriminatorvalue">
<h2>&#64;DefaultDiscriminatorValue<a class="headerlink" href="#defaultdiscriminatorvalue" title="Permalink to this headline"></a></h2>
<p>This annotation can be used when using <a class="reference internal" href="#discriminatorfield">&#64;DiscriminatorField</a>. 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.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @InheritanceType(&quot;SINGLE_COLLECTION&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> * @DiscriminatorMap({&quot;person&quot; = &quot;Person&quot;, &quot;employee&quot; = &quot;Employee&quot;})</span>
<span class="sd"> * @DefaultDiscriminatorValue(&quot;person&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Person</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="discriminatorfield">
<h2>&#64;DiscriminatorField<a class="headerlink" href="#discriminatorfield" title="Permalink to this headline"></a></h2>
<p>This annotation is required for the top-most class in a
<a class="reference internal" href="inheritance-mapping.html#single-collection-inheritance"><span class="std std-ref">single collection inheritance</span></a> 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.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @InheritanceType(&quot;SINGLE_COLLECTION&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">SuperUser</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For backwards compatibility, the discriminator field may also be specified
via either the <code class="docutils literal"><span class="pre">name</span></code> or <code class="docutils literal"><span class="pre">fieldName</span></code> annotation attributes.</p>
</div>
</div>
<div class="section" id="discriminatormap">
<h2>&#64;DiscriminatorMap<a class="headerlink" href="#discriminatormap" title="Permalink to this headline"></a></h2>
<p>This annotation is required for the top-most class in a
<a class="reference internal" href="inheritance-mapping.html#single-collection-inheritance"><span class="std std-ref">single collection inheritance</span></a> hierarchy.
It takes an array as its only argument, which maps keys to class names. The
class names may be fully qualified or relative to the current namespace. When
a document is persisted to the database, its class name key will be stored in
the discriminator field instead of the <a href="#id2"><span class="problematic" id="id3">|FQCN|</span></a>.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @InheritanceType(&quot;SINGLE_COLLECTION&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> * @DiscriminatorMap({&quot;person&quot; = &quot;Person&quot;, &quot;employee&quot; = &quot;Employee&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Person</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="distance">
<span id="annotation-distance"></span><h2>&#64;Distance<a class="headerlink" href="#distance" title="Permalink to this headline"></a></h2>
<p>This annotation can be used in combination with geospatial indexes and the
<a class="reference internal" href="geospatial-queries.html#geonear"><span class="std std-ref">geoNear()</span></a> query method to populate the property with the
calculated distance value.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @Index(keys={&quot;coordinates&quot;=&quot;2d&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Place</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">public</span> <span class="nv">$id</span><span class="p">;</span>
<span class="sd">/** @EmbedOne(targetDocument=&quot;Coordinates&quot;) */</span>
<span class="k">public</span> <span class="nv">$coordinates</span><span class="p">;</span>
<span class="sd">/** @Distance */</span>
<span class="k">public</span> <span class="nv">$distance</span><span class="p">;</span>
<span class="p">}</span>
<span class="sd">/** @EmbeddedDocument */</span>
<span class="k">class</span> <span class="nc">Coordinates</span>
<span class="p">{</span>
<span class="sd">/** @Field(type=&quot;float&quot;) */</span>
<span class="k">public</span> <span class="nv">$latitude</span><span class="p">;</span>
<span class="sd">/** @Field(type=&quot;float&quot;) */</span>
<span class="k">public</span> <span class="nv">$longitude</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Now you can run a <a class="reference external" href="https://docs.mongodb.com/manual/reference/command/geoNear/">geoNear command</a> and access the computed distance. The
following example would return the distance of the city nearest the query
coordinates:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$city</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">dm</span><span class="o">-&gt;</span><span class="na">createQuery</span><span class="p">(</span><span class="s1">&#39;City&#39;</span><span class="p">)</span>
<span class="o">-&gt;</span><span class="na">geoNear</span><span class="p">(</span><span class="mi">50</span><span class="p">,</span> <span class="mi">60</span><span class="p">)</span>
<span class="o">-&gt;</span><span class="na">limit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="o">-&gt;</span><span class="na">getQuery</span><span class="p">()</span>
<span class="o">-&gt;</span><span class="na">getSingleResult</span><span class="p">();</span>
<span class="k">echo</span> <span class="nv">$city</span><span class="o">-&gt;</span><span class="na">distance</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="document">
<h2>&#64;Document<a class="headerlink" href="#document" title="Permalink to this headline"></a></h2>
<p>Required annotation to mark a PHP class as a document, whose peristence will be
managed by ODM.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>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.</li>
<li>collection - By default, the collection name is derived from the document's
class name, but this option may be used to override that behavior.</li>
<li>repositoryClass - Specifies a custom repository class to use.</li>
<li>indexes - Specifies an array of indexes for this document.</li>
<li>readOnly - Prevents document from being updated: it can only be inserted,
upserted or removed.</li>
<li>requireIndexes - Specifies whether or not queries for this document should
require indexes by default. This may also be specified per query.</li>
<li>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 <a class="reference internal" href="working-with-objects.html#flush-options"><span class="std std-ref">option</span></a> to the <code class="docutils literal"><span class="pre">flush</span></code>
method when committing your documents.</li>
</ul>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document(</span>
<span class="sd"> * db=&quot;documents&quot;,</span>
<span class="sd"> * collection=&quot;users&quot;,</span>
<span class="sd"> * repositoryClass=&quot;MyProject\UserRepository&quot;,</span>
<span class="sd"> * indexes={</span>
<span class="sd"> * @Index(keys={&quot;username&quot;=&quot;desc&quot;}, options={&quot;unique&quot;=true})</span>
<span class="sd"> * },</span>
<span class="sd"> * readOnly=true,</span>
<span class="sd"> * requireIndexes=true</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Requiring Indexes was deprecated in 1.2 and will be removed in 2.0.</p>
</div>
</div>
<div class="section" id="embedmany">
<h2>&#64;EmbedMany<a class="headerlink" href="#embedmany" title="Permalink to this headline"></a></h2>
<p>This annotation is similar to <a class="reference internal" href="#embedone">&#64;EmbedOne</a>, but instead of embedding one
document, it embeds a collection of documents.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>targetDocument - A <a href="#id4"><span class="problematic" id="id5">|FQCN|</span></a> of the target document.</li>
<li>discriminatorField - The database field name to store the discriminator
value within the embedded document.</li>
<li>discriminatorMap - Map of discriminator values to class names.</li>
<li>defaultDiscriminatorValue - A default value for discriminatorField if no value
has been set in the embedded document.</li>
<li>strategy - The strategy used to persist changes to the collection. Possible
values are <code class="docutils literal"><span class="pre">addToSet</span></code>, <code class="docutils literal"><span class="pre">pushAll</span></code>, <code class="docutils literal"><span class="pre">set</span></code>, and <code class="docutils literal"><span class="pre">setArray</span></code>. <code class="docutils literal"><span class="pre">pushAll</span></code>
is the default. See <a class="reference internal" href="storage-strategies.html#storage-strategies"><span class="std std-ref">Storage Strategies</span></a> for more information.</li>
<li>collectionClass - A <a href="#id6"><span class="problematic" id="id7">|FQCN|</span></a> of class that implements <code class="docutils literal"><span class="pre">Collection</span></code> interface
and is used to hold documents. Doctrine's <code class="docutils literal"><span class="pre">ArrayCollection</span></code> is used by default.</li>
</ul>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @EmbedMany(</span>
<span class="sd"> * strategy=&quot;set&quot;,</span>
<span class="sd"> * discriminatorField=&quot;type&quot;,</span>
<span class="sd"> * discriminatorMap={</span>
<span class="sd"> * &quot;book&quot;=&quot;Documents\BookTag&quot;,</span>
<span class="sd"> * &quot;song&quot;=&quot;Documents\SongTag&quot;</span>
<span class="sd"> * },</span>
<span class="sd"> * defaultDiscriminatorValue=&quot;book&quot;</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">private</span> <span class="nv">$tags</span> <span class="o">=</span> <span class="k">array</span><span class="p">();</span>
</pre></div>
</div>
<p>Depending on the embedded document's class, a value of <code class="docutils literal"><span class="pre">user</span></code> or <code class="docutils literal"><span class="pre">author</span></code>
will be stored in the <code class="docutils literal"><span class="pre">type</span></code> field and used to reconstruct the proper class
during hydration. The <code class="docutils literal"><span class="pre">type</span></code> field need not be mapped on the embedded
document classes.</p>
</div>
<div class="section" id="embedone">
<h2>&#64;EmbedOne<a class="headerlink" href="#embedone" title="Permalink to this headline"></a></h2>
<p>The <a class="reference internal" href="#embedone">&#64;EmbedOne</a> annotation works similarly to <a class="reference internal" href="#referenceone">&#64;ReferenceOne</a>, except that
that document will be embedded within the parent document. Consider the
following excerpt from the MongoDB documentation:</p>
<blockquote>
<div>The key question in MongoDB schema design is &quot;does this object merit its own
collection, or rather should it be embedded within objects in other
collections?&quot; 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, &quot;why would I not want
to embed this object?&quot;</div></blockquote>
<p>Optional attributes:</p>
<ul class="simple">
<li>targetDocument - A <a href="#id8"><span class="problematic" id="id9">|FQCN|</span></a> of the target document.</li>
<li>discriminatorField - The database field name to store the discriminator
value within the embedded document.</li>
<li>discriminatorMap - Map of discriminator values to class names.</li>
<li>defaultDiscriminatorValue - A default value for discriminatorField if no value
has been set in the embedded document.</li>
</ul>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @EmbedOne(</span>
<span class="sd"> * discriminatorField=&quot;type&quot;,</span>
<span class="sd"> * discriminatorMap={</span>
<span class="sd"> * &quot;user&quot;=&quot;Documents\User&quot;,</span>
<span class="sd"> * &quot;author&quot;=&quot;Documents\Author&quot;</span>
<span class="sd"> * },</span>
<span class="sd"> * defaultDiscriminatorValue=&quot;user&quot;</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">private</span> <span class="nv">$creator</span><span class="p">;</span>
</pre></div>
</div>
<p>Depending on the embedded document's class, a value of <code class="docutils literal"><span class="pre">user</span></code> or <code class="docutils literal"><span class="pre">author</span></code>
will be stored in the <code class="docutils literal"><span class="pre">type</span></code> field and used to reconstruct the proper class
during hydration. The <code class="docutils literal"><span class="pre">type</span></code> field need not be mapped on the embedded
document classes.</p>
</div>
<div class="section" id="embeddeddocument">
<h2>&#64;EmbeddedDocument<a class="headerlink" href="#embeddeddocument" title="Permalink to this headline"></a></h2>
<p>Marks the document as embeddable. This annotation is required for any documents
to be stored within an <a class="reference internal" href="#embedone">&#64;EmbedOne</a> or <a class="reference internal" href="#embedmany">&#64;EmbedMany</a> relationship.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @EmbeddedDocument */</span>
<span class="k">class</span> <span class="nc">Money</span>
<span class="p">{</span>
<span class="sd">/** @Field(type=&quot;float&quot;) */</span>
<span class="k">private</span> <span class="nv">$amount</span><span class="p">;</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">__construct</span><span class="p">(</span><span class="nv">$amount</span><span class="p">)</span>
<span class="p">{</span>
<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">amount</span> <span class="o">=</span> <span class="p">(</span><span class="nx">float</span><span class="p">)</span> <span class="nv">$amount</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">//...</span>
<span class="p">}</span>
<span class="sd">/** @Document(db=&quot;finance&quot;, collection=&quot;wallets&quot;) */</span>
<span class="k">class</span> <span class="nc">Wallet</span>
<span class="p">{</span>
<span class="sd">/** @EmbedOne(targetDocument=&quot;Money&quot;) */</span>
<span class="k">private</span> <span class="nv">$money</span><span class="p">;</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">setMoney</span><span class="p">(</span><span class="nx">Money</span> <span class="nv">$money</span><span class="p">)</span>
<span class="p">{</span>
<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">money</span> <span class="o">=</span> <span class="nv">$money</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">//...</span>
<span class="p">}</span>
<span class="c1">//...</span>
<span class="nv">$wallet</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Wallet</span><span class="p">();</span>
<span class="nv">$wallet</span><span class="o">-&gt;</span><span class="na">setMoney</span><span class="p">(</span><span class="k">new</span> <span class="nx">Money</span><span class="p">(</span><span class="mf">34.39</span><span class="p">));</span>
<span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">persist</span><span class="p">(</span><span class="nv">$wallet</span><span class="p">);</span>
<span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">flush</span><span class="p">();</span>
</pre></div>
</div>
<p>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!</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>indexes - Specifies an array of indexes for this embedded document, to be
included in the schemas of any embedding documents.</li>
</ul>
</div>
<div class="section" id="field">
<h2>&#64;Field<a class="headerlink" href="#field" title="Permalink to this headline"></a></h2>
<p>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.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>type - Name of the ODM type, which will determine the value's representation
in PHP and BSON (i.e. MongoDB). See <a class="reference internal" href="basic-mapping.html#doctrine-mapping-types"><span class="std std-ref">Doctrine Mapping Types</span></a> for a list
of types. Defaults to &quot;string&quot;.</li>
<li>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.</li>
<li>nullable - By default, ODM will <code class="docutils literal"><span class="pre">$unset</span></code> 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.</li>
</ul>
<p>Examples:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Field(type=&quot;string&quot;)</span>
<span class="sd"> */</span>
<span class="k">protected</span> <span class="nv">$username</span><span class="p">;</span>
<span class="sd">/**</span>
<span class="sd"> * @Field(type=&quot;string&quot;, name=&quot;co&quot;)</span>
<span class="sd"> */</span>
<span class="k">protected</span> <span class="nv">$country</span><span class="p">;</span>
<span class="sd">/**</span>
<span class="sd"> * @Field(type=&quot;float&quot;)</span>
<span class="sd"> */</span>
<span class="k">protected</span> <span class="nv">$height</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="file">
<h2>&#64;File<a class="headerlink" href="#file" title="Permalink to this headline"></a></h2>
<p>Marks an annotated instance variable as a file. Additionally, this instructs ODM
to store the entire document in <a class="reference external" href="https://docs.mongodb.com/manual/core/gridfs/">GridFS</a>. Only a single field in a document may
be mapped as a file.</p>
<p>The instance variable will be an <code class="docutils literal"><span class="pre">Doctrine\MongoDB\GridFSFile</span></code> object, which
is a wrapper class for <a class="reference external" href="http://php.net/manual/en/class.mongogridfsfile.php">MongoGridFSFile</a> and facilitates access to the file
data in GridFS. If the variable is a file path string when the document is first
persisted, ODM will convert it to GridFSFile object automatically.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @File */</span>
<span class="k">private</span> <span class="nv">$file</span><span class="p">;</span>
</pre></div>
</div>
<p>Additional fields can be mapped in GridFS documents like any other, but metadata
fields set by the driver (e.g. <code class="docutils literal"><span class="pre">length</span></code>) should be mapped with <a class="reference internal" href="#notsaved">&#64;NotSaved</a> so
as not to inadvertently overwrite them. Some metadata fields, such as
<code class="docutils literal"><span class="pre">filename</span></code> may be modified and do not require <a class="reference internal" href="#notsaved">&#64;NotSaved</a>. In the following
example, we also add a custom field to refer to the corresponding User document
that created the file.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;string&quot;) */</span>
<span class="k">private</span> <span class="nv">$filename</span><span class="p">;</span>
<span class="sd">/** @NotSaved(type=&quot;int&quot;) */</span>
<span class="k">private</span> <span class="nv">$length</span><span class="p">;</span>
<span class="sd">/** @NotSaved(type=&quot;string&quot;) */</span>
<span class="k">private</span> <span class="nv">$md5</span><span class="p">;</span>
<span class="sd">/** @NotSaved(type=&quot;date&quot;) */</span>
<span class="k">private</span> <span class="nv">$uploadDate</span><span class="p">;</span>
<span class="sd">/** @ReferenceOne(targetDocument=&quot;Documents\User&quot;) */</span>
<span class="k">private</span> <span class="nv">$uploadedBy</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="float">
<h2>&#64;Float<a class="headerlink" href="#float" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;float&quot;.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated because it uses a keyword that was reserved in
PHP 7. It will be removed in ODM 2.0. Please use the <a class="reference internal" href="#field">&#64;Field</a> annotation
with type &quot;float&quot;.</p>
</div>
</div>
<div class="section" id="haslifecyclecallbacks">
<span id="id1"></span><h2>&#64;HasLifecycleCallbacks<a class="headerlink" href="#haslifecyclecallbacks" title="Permalink to this headline"></a></h2>
<p>This annotation must be set on the document class to instruct Doctrine to check
for lifecycle callback annotations on public methods. Using <a class="reference internal" href="#preflush">&#64;PreFlush</a>,
<a class="reference internal" href="#preload">&#64;PreLoad</a>, <a class="reference internal" href="#postload">&#64;PostLoad</a>, <a class="reference internal" href="#prepersist">&#64;PrePersist</a>, <a class="reference internal" href="#postpersist">&#64;PostPersist</a>, <a class="reference internal" href="#preremove">&#64;PreRemove</a>,
<a class="reference internal" href="#postremove">&#64;PostRemove</a>, <a class="reference internal" href="#preupdate">&#64;PreUpdate</a>, or <a class="reference internal" href="#postupdate">&#64;PostUpdate</a> on methods without this
annotation will cause Doctrine to ignore the callbacks.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @PostPersist */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">sendWelcomeEmail</span><span class="p">()</span> <span class="p">{}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="hash">
<h2>&#64;Hash<a class="headerlink" href="#hash" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;hash&quot;. Stores and retrieves
the value as an associative array.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;hash&quot;.</p>
</div>
</div>
<div class="section" id="id">
<h2>&#64;Id<a class="headerlink" href="#id" title="Permalink to this headline"></a></h2>
<p>The annotated instance variable will be marked as the document identifier. The
default behavior is to store a <a class="reference external" href="http://php.net/manual/en/class.mongoid.php">MongoId</a> instance, but you may customize this
via the <a class="reference internal" href="basic-mapping.html#basic-mapping-identifiers"><span class="std std-ref">strategy</span></a> attribute.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">protected</span> <span class="nv">$id</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="increment">
<h2>&#64;Increment<a class="headerlink" href="#increment" title="Permalink to this headline"></a></h2>
<p>The increment type is just like an integer field, except that it will be updated
using the <code class="docutils literal"><span class="pre">$inc</span></code> operator instead of <code class="docutils literal"><span class="pre">$set</span></code>:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">class</span> <span class="nc">Package</span>
<span class="p">{</span>
<span class="sd">/** @Increment */</span>
<span class="k">private</span> <span class="nv">$downloads</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">incrementDownloads</span><span class="p">()</span>
<span class="p">{</span>
<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">downloads</span><span class="o">++</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Now, update a Package instance like so:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$package</span><span class="o">-&gt;</span><span class="na">incrementDownloads</span><span class="p">();</span>
<span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">flush</span><span class="p">();</span>
</pre></div>
</div>
<p>The query sent to Mongo would resemble the following:</p>
<div class="highlight-json"><div class="highlight"><pre><span class="p">{</span> <span class="nt">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&quot;downloads&quot;</span><span class="p">:</span> <span class="mi">1</span> <span class="p">}</span> <span class="p">}</span>
</pre></div>
</div>
<p>The field will be incremented by the difference between the new and old values.
This is useful if many requests are attempting to update the field concurrently.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;int&quot; or &quot;float&quot; and use the &quot;increment&quot;
strategy.</p>
</div>
</div>
<div class="section" id="index">
<h2>&#64;Index<a class="headerlink" href="#index" title="Permalink to this headline"></a></h2>
<p>This annotation is used inside of the class-level <a class="reference internal" href="#document">&#64;Document</a> or
<a class="reference internal" href="#embeddeddocument">&#64;EmbeddedDocument</a> annotations to specify indexes to be created on the
collection (or embedding document's collection in the case of
<a class="reference internal" href="#embeddeddocument">&#64;EmbeddedDocument</a>). It may also be used at the property-level to define
single-field indexes.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>keys - Mapping of indexed fields to their ordering or index type. ODM will
allow &quot;asc&quot; and &quot;desc&quot; to be used in place of <code class="docutils literal"><span class="pre">1</span></code> and <code class="docutils literal"><span class="pre">-1</span></code>,
respectively. Special index types (e.g. &quot;2dsphere&quot;) should be specified as
strings. This is required when <a class="reference internal" href="#index">&#64;Index</a> is used at the class level.</li>
<li>options - Options for creating the index</li>
</ul>
<p>The <code class="docutils literal"><span class="pre">keys</span></code> and <code class="docutils literal"><span class="pre">options</span></code> attributes correspond to the arguments for
<a class="reference external" href="http://php.net/manual/en/mongocollection.createindex.php">MongoCollection::createIndex()</a>.
ODM allows mapped field names (i.e. PHP property names) to be used when defining
<code class="docutils literal"><span class="pre">keys</span></code>.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document(</span>
<span class="sd"> * indexes={</span>
<span class="sd"> * @Index(keys={&quot;username&quot;=&quot;desc&quot;}, options={&quot;unique&quot;=true})</span>
<span class="sd"> * }</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If you are creating a single-field index, you can simply specify an <a class="reference internal" href="#index">&#64;Index</a> or
<a class="reference internal" href="#uniqueindex">&#64;UniqueIndex</a> on a mapped property:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @UniqueIndex */</span>
<span class="k">private</span> <span class="nv">$username</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="indexes">
<h2>&#64;Indexes<a class="headerlink" href="#indexes" title="Permalink to this headline"></a></h2>
<p>This annotation may be used at the class level to specify an array of <a class="reference internal" href="#index">&#64;Index</a>
annotations. It is functionally equivalent to using the <code class="docutils literal"><span class="pre">indexes</span></code> option for
the <a class="reference internal" href="#document">&#64;Document</a> or <a class="reference internal" href="#embeddeddocument">&#64;EmbeddedDocument</a> annotations.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @Indexes({</span>
<span class="sd"> * @Index(keys={&quot;username&quot;=&quot;desc&quot;}, options={&quot;unique&quot;=true})</span>
<span class="sd"> * })</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="inheritancetype">
<h2>&#64;InheritanceType<a class="headerlink" href="#inheritancetype" title="Permalink to this headline"></a></h2>
<p>This annotation must appear on the top-most class in an
<a class="reference internal" href="inheritance-mapping.html#inheritance-mapping"><span class="std std-ref">inheritance hierarchy</span></a>. <code class="docutils literal"><span class="pre">SINGLE_COLLECTION</span></code> and
<code class="docutils literal"><span class="pre">COLLECTION_PER_CLASS</span></code> are currently supported.</p>
<p>Examples:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @InheritanceType(&quot;COLLECTION_PER_CLASS&quot;)</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Person</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @InheritanceType(&quot;SINGLE_COLLECTION&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> * @DiscriminatorMap({&quot;person&quot;=&quot;Person&quot;, &quot;employee&quot;=&quot;Employee&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Person</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="int">
<h2>&#64;Int<a class="headerlink" href="#int" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;int&quot;.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Int */</span>
<span class="k">private</span> <span class="nv">$columns</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated because it uses a keyword that was reserved in
PHP 7. It will be removed in ODM 2.0. Please use the <a class="reference internal" href="#field">&#64;Field</a> annotation
with type &quot;int&quot;.</p>
</div>
</div>
<div class="section" id="integer">
<h2>&#64;Integer<a class="headerlink" href="#integer" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;integer&quot;. Internally it uses
exactly same logic as <a class="reference internal" href="#int">&#64;Int</a> annotation and &quot;int&quot; type.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Integer */</span>
<span class="k">private</span> <span class="nv">$columns</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;int&quot;.</p>
</div>
</div>
<div class="section" id="key">
<h2>&#64;Key<a class="headerlink" href="#key" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;key&quot;. The value will be
converted to <a class="reference external" href="http://php.net/manual/en/class.mongomaxkey.php">MongoMaxKey</a> or <a class="reference external" href="http://php.net/manual/en/class.mongominkey.php">MongoMinKey</a> if it is true or false,
respectively.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The BSON MaxKey and MinKey types are internally used by MongoDB for indexing
and sharding. There is generally no reason to use these in an application.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;key&quot;.</p>
</div>
</div>
<div class="section" id="lock">
<span id="annotations-reference-lock"></span><h2>&#64;Lock<a class="headerlink" href="#lock" title="Permalink to this headline"></a></h2>
<p>The annotated instance variable will be used to store lock information for <a class="reference internal" href="transactions-and-concurrency.html#transactions-and-concurrency-pessimistic-locking"><span class="std std-ref">pessimistic locking</span></a>.
This is only compatible with the <code class="docutils literal"><span class="pre">int</span></code> type, and cannot be combined with <a class="reference internal" href="#id">&#64;Id</a>.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;int&quot;) @Lock */</span>
<span class="k">private</span> <span class="nv">$lock</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="mappedsuperclass">
<h2>&#64;MappedSuperclass<a class="headerlink" href="#mappedsuperclass" title="Permalink to this headline"></a></h2>
<p>The annotation is used to specify classes that are parents of document classes
and should not be managed directly. See
<a class="reference internal" href="inheritance-mapping.html#inheritance-mapping"><span class="std std-ref">inheritance mapping</span></a> for additional information.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @MappedSuperclass */</span>
<span class="k">class</span> <span class="nc">BaseDocument</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="notsaved">
<h2>&#64;NotSaved<a class="headerlink" href="#notsaved" title="Permalink to this headline"></a></h2>
<p>The annotation is used to specify properties that are loaded if they exist in
MongoDB; however, ODM will not save the property value back to the database.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @NotSaved */</span>
<span class="k">public</span> <span class="nv">$field</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="postload">
<h2>&#64;PostLoad<a class="headerlink" href="#postload" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">postLoad</span></code> event. The
<a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for the
method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PostLoad */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">postLoad</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="postpersist">
<h2>&#64;PostPersist<a class="headerlink" href="#postpersist" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">postPersist</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PostPersist */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">postPersist</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="postremove">
<h2>&#64;PostRemove<a class="headerlink" href="#postremove" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">postRemove</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PostRemove */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">postRemove</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="postupdate">
<h2>&#64;PostUpdate<a class="headerlink" href="#postupdate" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">postUpdate</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PostUpdate */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">postUpdate</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="preflush">
<h2>&#64;PreFlush<a class="headerlink" href="#preflush" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">preFlush</span></code> event. The
<a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for the
method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PreFlush */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">preFlush</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="preload">
<h2>&#64;PreLoad<a class="headerlink" href="#preload" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">preLoad</span></code> event. The
<a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for the
method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">use</span> <span class="nx">Doctrine\ODM\MongoDB\Event\PreLoadEventArgs</span><span class="p">;</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PreLoad */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">preLoad</span><span class="p">(</span><span class="nx">PreLoadEventArgs</span> <span class="nv">$eventArgs</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="prepersist">
<h2>&#64;PrePersist<a class="headerlink" href="#prepersist" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">prePersist</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PrePersist */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">prePersist</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="preremove">
<h2>&#64;PreRemove<a class="headerlink" href="#preremove" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">preRemove</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PreRemove */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">preRemove</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="preupdate">
<h2>&#64;PreUpdate<a class="headerlink" href="#preupdate" title="Permalink to this headline"></a></h2>
<p>Marks a method on the document class to be called on the <code class="docutils literal"><span class="pre">preUpdate</span></code> event.
The <a class="reference internal" href="#id1">&#64;HasLifecycleCallbacks</a> annotation must be present on the same class for
the method to be registered.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Document @HasLifecycleCallbacks */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @PreUpdate */</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">preUpdated</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="events.html#lifecycle-events"><span class="std std-ref">Lifecycle Events</span></a> for more information.</p>
</div>
<div class="section" id="readpreference">
<h2>&#64;ReadPreference<a class="headerlink" href="#readpreference" title="Permalink to this headline"></a></h2>
<p>Specifies <cite>Read Preference &lt;https://docs.mongodb.com/manual/core/read-preference/&gt;_</cite>
that will be applied when querying for the annotated document.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">Documents</span><span class="p">;</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @ODM\ReadPreference(&quot;primaryPreferred&quot;, tags={</span>
<span class="sd"> * { &quot;dc&quot;=&quot;east&quot; },</span>
<span class="sd"> * { &quot;dc&quot;=&quot;west&quot; },</span>
<span class="sd"> * { }</span>
<span class="sd"> * })</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation can not be combined with <code class="docutils literal"><span class="pre">slaveOkay</span></code>, such combination will
produce a <code class="docutils literal"><span class="pre">MappingException</span></code> error.</p>
</div>
</div>
<div class="section" id="referencemany">
<span id="annotations-reference-reference-many"></span><h2>&#64;ReferenceMany<a class="headerlink" href="#referencemany" title="Permalink to this headline"></a></h2>
<p>Defines that the annotated instance variable holds a collection of referenced
documents.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>targetDocument - A <a href="#id10"><span class="problematic" id="id11">|FQCN|</span></a> of the target document. A <code class="docutils literal"><span class="pre">targetDocument</span></code> is
required when using <code class="docutils literal"><span class="pre">storeAs:</span> <span class="pre">id</span></code>.</li>
<li>simple - deprecated (use <code class="docutils literal"><span class="pre">storeAs:</span> <span class="pre">id</span></code>)</li>
<li>storeAs - Indicates how to store the reference. <code class="docutils literal"><span class="pre">id</span></code> stores the identifier,
<code class="docutils literal"><span class="pre">ref</span></code> an embedded object containing the <code class="docutils literal"><span class="pre">id</span></code> field and (optionally) a
discriminator. <code class="docutils literal"><span class="pre">dbRef</span></code> and <code class="docutils literal"><span class="pre">dbRefWithDb</span></code> store a <a class="reference external" href="https://docs.mongodb.com/manual/reference/database-references/#dbrefs">DBRef</a> object and
are deprecated in favor of <code class="docutils literal"><span class="pre">ref</span></code>. Note that <code class="docutils literal"><span class="pre">id</span></code> references are not
compatible with the discriminators.</li>
<li>cascade - Cascade Option</li>
<li>discriminatorField - The field name to store the discriminator value within
the reference object.</li>
<li>discriminatorMap - Map of discriminator values to class names.</li>
<li>defaultDiscriminatorValue - A default value for discriminatorField if no value
has been set in the referenced document.</li>
<li>inversedBy - The field name of the inverse side. Only allowed on owning side.</li>
<li>mappedBy - The field name of the owning side. Only allowed on the inverse side.</li>
<li>repositoryMethod - The name of the repository method to call to populate this reference.</li>
<li>sort - The default sort for the query that loads the reference.</li>
<li>criteria - Array of default criteria for the query that loads the reference.</li>
<li>limit - Limit for the query that loads the reference.</li>
<li>skip - Skip for the query that loads the reference.</li>
<li>strategy - The strategy used to persist changes to the collection. Possible
values are <code class="docutils literal"><span class="pre">addToSet</span></code>, <code class="docutils literal"><span class="pre">pushAll</span></code>, <code class="docutils literal"><span class="pre">set</span></code>, and <code class="docutils literal"><span class="pre">setArray</span></code>. <code class="docutils literal"><span class="pre">pushAll</span></code>
is the default. See <a class="reference internal" href="storage-strategies.html#storage-strategies"><span class="std std-ref">Storage Strategies</span></a> for more information.</li>
<li>collectionClass - A <a href="#id12"><span class="problematic" id="id13">|FQCN|</span></a> of class that implements <code class="docutils literal"><span class="pre">Collection</span></code> interface
and is used to hold documents. Doctrine's <code class="docutils literal"><span class="pre">ArrayCollection</span></code> is used by default</li>
<li>prime - A list of references contained in the target document that will be
initialized when the collection is loaded. Only allowed for inverse
references.</li>
</ul>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @ReferenceMany(</span>
<span class="sd"> * strategy=&quot;set&quot;,</span>
<span class="sd"> * targetDocument=&quot;Documents\Item&quot;,</span>
<span class="sd"> * cascade=&quot;all&quot;,</span>
<span class="sd"> * sort={&quot;sort_field&quot;: &quot;asc&quot;}</span>
<span class="sd"> * discriminatorField=&quot;type&quot;,</span>
<span class="sd"> * discriminatorMap={</span>
<span class="sd"> * &quot;book&quot;=&quot;Documents\BookItem&quot;,</span>
<span class="sd"> * &quot;song&quot;=&quot;Documents\SongItem&quot;</span>
<span class="sd"> * },</span>
<span class="sd"> * defaultDiscriminatorValue=&quot;book&quot;</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">private</span> <span class="nv">$cart</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="referenceone">
<span id="annotations-reference-reference-one"></span><h2>&#64;ReferenceOne<a class="headerlink" href="#referenceone" title="Permalink to this headline"></a></h2>
<p>Defines an instance variable holds a related document instance.</p>
<p>Optional attributes:</p>
<ul class="simple">
<li>targetDocument - A <a href="#id14"><span class="problematic" id="id15">|FQCN|</span></a> of the target document. A <code class="docutils literal"><span class="pre">targetDocument</span></code> is
required when using <code class="docutils literal"><span class="pre">storeAs:</span> <span class="pre">id</span></code>.</li>
<li>simple - deprecated (use <code class="docutils literal"><span class="pre">storeAs:</span> <span class="pre">id</span></code>)</li>
<li>storeAs - Indicates how to store the reference. <code class="docutils literal"><span class="pre">id</span></code> stores the identifier,
<code class="docutils literal"><span class="pre">ref</span></code> an embedded object containing the <code class="docutils literal"><span class="pre">id</span></code> field and (optionally) a
discriminator. <code class="docutils literal"><span class="pre">dbRef</span></code> and <code class="docutils literal"><span class="pre">dbRefWithDb</span></code> store a <a class="reference external" href="https://docs.mongodb.com/manual/reference/database-references/#dbrefs">DBRef</a> object and
are deprecated in favor of <code class="docutils literal"><span class="pre">ref</span></code>. Note that <code class="docutils literal"><span class="pre">id</span></code> references are not
compatible with the discriminators.</li>
<li>cascade - Cascade Option</li>
<li>discriminatorField - The field name to store the discriminator value within
the reference object.</li>
<li>discriminatorMap - Map of discriminator values to class names.</li>
<li>defaultDiscriminatorValue - A default value for discriminatorField if no value
has been set in the referenced document.</li>
<li>inversedBy - The field name of the inverse side. Only allowed on owning side.</li>
<li>mappedBy - The field name of the owning side. Only allowed on the inverse side.</li>
<li>repositoryMethod - The name of the repository method to call to populate this reference.</li>
<li>sort - The default sort for the query that loads the reference.</li>
<li>criteria - Array of default criteria for the query that loads the reference.</li>
<li>limit - Limit for the query that loads the reference.</li>
<li>skip - Skip for the query that loads the reference.</li>
</ul>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @ReferenceOne(</span>
<span class="sd"> * targetDocument=&quot;Documents\Item&quot;,</span>
<span class="sd"> * cascade=&quot;all&quot;,</span>
<span class="sd"> * discriminatorField=&quot;type&quot;,</span>
<span class="sd"> * discriminatorMap={</span>
<span class="sd"> * &quot;book&quot;=&quot;Documents\BookItem&quot;,</span>
<span class="sd"> * &quot;song&quot;=&quot;Documents\SongItem&quot;</span>
<span class="sd"> * },</span>
<span class="sd"> * defaultDiscriminatorValue=&quot;book&quot;</span>
<span class="sd"> * )</span>
<span class="sd"> */</span>
<span class="k">private</span> <span class="nv">$cart</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="shardkey">
<h2>&#64;ShardKey<a class="headerlink" href="#shardkey" title="Permalink to this headline"></a></h2>
<p>This annotation may be used at the class level to specify a shard key to be used
for sharding the document collection.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document</span>
<span class="sd"> * @ShardKey(keys={&quot;username&quot;=&quot;asc&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="string">
<h2>&#64;String<a class="headerlink" href="#string" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;string&quot;.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @String */</span>
<span class="k">private</span> <span class="nv">$username</span><span class="p">;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated because it uses a keyword that was reserved in
PHP 7. It will be removed in ODM 2.0. Please use the <a class="reference internal" href="#field">&#64;Field</a> annotation
with type &quot;string&quot;.</p>
</div>
</div>
<div class="section" id="timestamp">
<h2>&#64;Timestamp<a class="headerlink" href="#timestamp" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#field">&#64;Field</a>, with &quot;type&quot; attribute set to &quot;timestamp&quot;. The value will be
converted to <a class="reference external" href="http://php.net/manual/en/class.mongotimestamp.php">MongoTimestamp</a> for storage in MongoDB.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The BSON timestamp type is an internal type used for MongoDB's replication
and sharding. If you need to store dates in your application, you should use
the &quot;date&quot; type instead.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This annotation is deprecated and will be removed in ODM 2.0. Please use the
<a class="reference internal" href="#field">&#64;Field</a> annotation with type &quot;timestamp&quot;.</p>
</div>
</div>
<div class="section" id="uniqueindex">
<h2>&#64;UniqueIndex<a class="headerlink" href="#uniqueindex" title="Permalink to this headline"></a></h2>
<p>Alias of <a class="reference internal" href="#index">&#64;Index</a>, with the <code class="docutils literal"><span class="pre">unique</span></code> option set by default.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;string&quot;) @UniqueIndex */</span>
<span class="k">private</span> <span class="nv">$email</span><span class="p">;</span>
</pre></div>
</div>
</div>
<div class="section" id="version">
<span id="annotations-reference-version"></span><h2>&#64;Version<a class="headerlink" href="#version" title="Permalink to this headline"></a></h2>
<p>The annotated instance variable will be used to store version information for <a class="reference internal" href="transactions-and-concurrency.html#transactions-and-concurrency-optimistic-locking"><span class="std std-ref">optimistic locking</span></a>.
This is only compatible with <code class="docutils literal"><span class="pre">int</span></code> and <code class="docutils literal"><span class="pre">date</span></code> field types, and cannot be combined with <a class="reference internal" href="#id">&#64;Id</a>.</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(type=&quot;int&quot;) @Version */</span>
<span class="k">private</span> <span class="nv">$version</span><span class="p">;</span>
</pre></div>
</div>
<p>By default, Doctrine ODM updates <a class="reference internal" href="embedded-mapping.html#embed-many"><span class="std std-ref">embed-many</span></a> and
<a class="reference internal" href="reference-mapping.html#reference-many"><span class="std std-ref">reference-many</span></a> collections in separate write operations,
which do not bump the document version. Users employing document versioning are
encouraged to use the <a class="reference internal" href="storage-strategies.html#atomic-set"><span class="std std-ref">atomicSet</span></a> or
<a class="reference internal" href="storage-strategies.html#atomic-set-array"><span class="std std-ref">atomicSetArray</span></a> strategies for such collections, which
will ensure that collections are updated in the same write operation as the
versioned parent document.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="">
<h3>Search</h3>
<form class="search" action="http://readthedocs.org/search/project/" method="get">
<input type="text" name="q" size="18">
<input type="submit" value="Go">
<input type="hidden" name="selected_facets" value="project:">
</form>
</div>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Annotations Reference</a><ul>
<li><a class="reference internal" href="#alsoload">&#64;AlsoLoad</a></li>
<li><a class="reference internal" href="#bin">&#64;Bin</a></li>
<li><a class="reference internal" href="#bincustom">&#64;BinCustom</a></li>
<li><a class="reference internal" href="#binfunc">&#64;BinFunc</a></li>
<li><a class="reference internal" href="#binmd5">&#64;BinMD5</a></li>
<li><a class="reference internal" href="#binuuid">&#64;BinUUID</a></li>
<li><a class="reference internal" href="#binuuidrfc4122">&#64;BinUUIDRFC4122</a></li>
<li><a class="reference internal" href="#bool">&#64;Bool</a></li>
<li><a class="reference internal" href="#boolean">&#64;Boolean</a></li>
<li><a class="reference internal" href="#changetrackingpolicy">&#64;ChangeTrackingPolicy</a></li>
<li><a class="reference internal" href="#collection">&#64;Collection</a></li>
<li><a class="reference internal" href="#date">&#64;Date</a></li>
<li><a class="reference internal" href="#defaultdiscriminatorvalue">&#64;DefaultDiscriminatorValue</a></li>
<li><a class="reference internal" href="#discriminatorfield">&#64;DiscriminatorField</a></li>
<li><a class="reference internal" href="#discriminatormap">&#64;DiscriminatorMap</a></li>
<li><a class="reference internal" href="#distance">&#64;Distance</a></li>
<li><a class="reference internal" href="#document">&#64;Document</a></li>
<li><a class="reference internal" href="#embedmany">&#64;EmbedMany</a></li>
<li><a class="reference internal" href="#embedone">&#64;EmbedOne</a></li>
<li><a class="reference internal" href="#embeddeddocument">&#64;EmbeddedDocument</a></li>
<li><a class="reference internal" href="#field">&#64;Field</a></li>
<li><a class="reference internal" href="#file">&#64;File</a></li>
<li><a class="reference internal" href="#float">&#64;Float</a></li>
<li><a class="reference internal" href="#haslifecyclecallbacks">&#64;HasLifecycleCallbacks</a></li>
<li><a class="reference internal" href="#hash">&#64;Hash</a></li>
<li><a class="reference internal" href="#id">&#64;Id</a></li>
<li><a class="reference internal" href="#increment">&#64;Increment</a></li>
<li><a class="reference internal" href="#index">&#64;Index</a></li>
<li><a class="reference internal" href="#indexes">&#64;Indexes</a></li>
<li><a class="reference internal" href="#inheritancetype">&#64;InheritanceType</a></li>
<li><a class="reference internal" href="#int">&#64;Int</a></li>
<li><a class="reference internal" href="#integer">&#64;Integer</a></li>
<li><a class="reference internal" href="#key">&#64;Key</a></li>
<li><a class="reference internal" href="#lock">&#64;Lock</a></li>
<li><a class="reference internal" href="#mappedsuperclass">&#64;MappedSuperclass</a></li>
<li><a class="reference internal" href="#notsaved">&#64;NotSaved</a></li>
<li><a class="reference internal" href="#postload">&#64;PostLoad</a></li>
<li><a class="reference internal" href="#postpersist">&#64;PostPersist</a></li>
<li><a class="reference internal" href="#postremove">&#64;PostRemove</a></li>
<li><a class="reference internal" href="#postupdate">&#64;PostUpdate</a></li>
<li><a class="reference internal" href="#preflush">&#64;PreFlush</a></li>
<li><a class="reference internal" href="#preload">&#64;PreLoad</a></li>
<li><a class="reference internal" href="#prepersist">&#64;PrePersist</a></li>
<li><a class="reference internal" href="#preremove">&#64;PreRemove</a></li>
<li><a class="reference internal" href="#preupdate">&#64;PreUpdate</a></li>
<li><a class="reference internal" href="#readpreference">&#64;ReadPreference</a></li>
<li><a class="reference internal" href="#referencemany">&#64;ReferenceMany</a></li>
<li><a class="reference internal" href="#referenceone">&#64;ReferenceOne</a></li>
<li><a class="reference internal" href="#shardkey">&#64;ShardKey</a></li>
<li><a class="reference internal" href="#string">&#64;String</a></li>
<li><a class="reference internal" href="#timestamp">&#64;Timestamp</a></li>
<li><a class="reference internal" href="#uniqueindex">&#64;UniqueIndex</a></li>
<li><a class="reference internal" href="#version">&#64;Version</a></li>
</ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/annotations-reference.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy; Copyright 2013, Doctrine Project Team.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.6.2.
<br/>
<a target="_BLANK" href="http://www.servergrove.com"><img src="http://www.doctrine-project.org/_static/servergrove.jpg" /></a> <br/><br/>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick" />
<input type="hidden" name="hosted_button_id" value="BAE2E3XANQ77Y" />
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!" />
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1" />
</form>
</div>
</div>
<div id="bot-rcnr">
<div class="tl"><!-- corner --></div>
</div>
</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-288343-7";
urchinTracker();
</script>
<a class="githublink" href="http://github.com/doctrine"><img src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink