will/mongodb-odm-docs-dash
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
77af067463
mongodb-odm-docs-dash/Doctrine ODM.docset/Contents/Resources/Documents/reference/basic-mapping.html

747 lines
47 KiB
HTML
Raw Blame History

<!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>Basic Mapping &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="basic-mapping">
<h1>Basic Mapping<a class="headerlink" href="#basic-mapping" title="Permalink to this headline"></a></h1>
<p>This chapter explains the basic mapping of objects and properties.
Mapping of references and embedded documents will be covered in the
next chapter &quot;Reference Mapping&quot;.</p>
<div class="section" id="mapping-drivers">
<h2>Mapping Drivers<a class="headerlink" href="#mapping-drivers" title="Permalink to this headline"></a></h2>
<p>Doctrine provides several different ways for specifying object
document mapping metadata:</p>
<ul class="simple">
<li>Docblock Annotations</li>
<li>XML</li>
<li>YAML</li>
<li>Raw PHP Code</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you're wondering which mapping driver gives the best
performance, the answer is: None. Once the metadata of a class has
been read from the source (annotations, xml or yaml) it is stored
in an instance of the
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Mapping\ClassMetadata</span></code> class and these
instances are stored in the metadata cache. Therefore at the end of
the day all drivers perform equally well. If you're not using a
metadata cache (not recommended!) then the XML driver might have a
slight edge in performance due to the powerful native XML support
in PHP.</p>
</div>
</div>
<div class="section" id="introduction-to-docblock-annotations">
<h2>Introduction to Docblock Annotations<a class="headerlink" href="#introduction-to-docblock-annotations" title="Permalink to this headline"></a></h2>
<p>You've probably used docblock annotations in some form already,
most likely to provide documentation metadata for a tool like
<code class="docutils literal"><span class="pre">PHPDocumentor</span></code> (&#64;author, &#64;link, ...). Docblock annotations are a
tool to embed metadata inside the documentation section which can
then be processed by some tool. Doctrine generalizes the concept of
docblock annotations so that they can be used for any kind of
metadata and so that it is easy to define new docblock annotations.
In order to allow more involved annotation values and to reduce the
chances of clashes with other docblock annotations, the Doctrine
docblock annotations feature an alternative syntax that is heavily
inspired by the Annotation syntax introduced in Java 5.</p>
<p>The implementation of these enhanced docblock annotations is
located in the <code class="docutils literal"><span class="pre">Doctrine\Common\Annotations</span></code> namespace and
therefore part of the Common package. Doctrine docblock annotations
support namespaces and nested annotations among other things. The
Doctrine MongoDB ODM defines its own set of docblock annotations
for supplying object document mapping metadata.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you're not comfortable with the concept of docblock
annotations, don't worry, as mentioned earlier Doctrine 2 provides
XML and YAML alternatives and you could easily implement your own
favorite mechanism for defining ORM metadata.</p>
</div>
</div>
<div class="section" id="persistent-classes">
<h2>Persistent classes<a class="headerlink" href="#persistent-classes" title="Permalink to this headline"></a></h2>
<p>In order to mark a class for object-relational persistence it needs
to be designated as a document. This can be done through the
<code class="docutils literal"><span class="pre">&#64;Document</span></code> marker annotation.</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">document</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>By default, the document will be persisted to a database named
doctrine and a collection with the same name as the class name. In
order to change that, you can use the <code class="docutils literal"><span class="pre">db</span></code> and <code class="docutils literal"><span class="pre">collection</span></code>
option as follows:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">/** @Document(db=&quot;my_db&quot;, collection=&quot;users&quot;) */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span> <span class="na">db=</span><span class="s">&quot;my_db&quot;</span> <span class="na">collection=</span><span class="s">&quot;users&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">document</span>
<span class="l l-Scalar l-Scalar-Plain">db</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">my_db</span>
<span class="l l-Scalar l-Scalar-Plain">collection</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">users</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>Now instances of <code class="docutils literal"><span class="pre">Documents\User</span></code> will be persisted into a
collection named <code class="docutils literal"><span class="pre">users</span></code> in the database <code class="docutils literal"><span class="pre">my_db</span></code>.</p>
<p>If you want to omit the db attribute you can configure the default db
to use with the <code class="docutils literal"><span class="pre">setDefaultDB</span></code> method:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$config</span><span class="o">-&gt;</span><span class="na">setDefaultDB</span><span class="p">(</span><span class="s1">&#39;my_db&#39;</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="doctrine-mapping-types">
<span id="id1"></span><h2>Doctrine Mapping Types<a class="headerlink" href="#doctrine-mapping-types" title="Permalink to this headline"></a></h2>
<p>A Doctrine Mapping Type defines the mapping between a PHP type and
an MongoDB type. You can even write your own custom mapping types.</p>
<p>Here is a quick overview of the built-in mapping types:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">bin</span></code></li>
<li><code class="docutils literal"><span class="pre">bin_bytearray</span></code></li>
<li><code class="docutils literal"><span class="pre">bin_custom</span></code></li>
<li><code class="docutils literal"><span class="pre">bin_func</span></code></li>
<li><code class="docutils literal"><span class="pre">bin_md5</span></code></li>
<li><code class="docutils literal"><span class="pre">bin_uuid</span></code></li>
<li><code class="docutils literal"><span class="pre">boolean</span></code></li>
<li><code class="docutils literal"><span class="pre">collection</span></code></li>
<li><code class="docutils literal"><span class="pre">custom_id</span></code></li>
<li><code class="docutils literal"><span class="pre">date</span></code></li>
<li><code class="docutils literal"><span class="pre">file</span></code></li>
<li><code class="docutils literal"><span class="pre">float</span></code></li>
<li><code class="docutils literal"><span class="pre">hash</span></code></li>
<li><code class="docutils literal"><span class="pre">id</span></code></li>
<li><code class="docutils literal"><span class="pre">int</span></code></li>
<li><code class="docutils literal"><span class="pre">key</span></code></li>
<li><code class="docutils literal"><span class="pre">object_id</span></code></li>
<li><code class="docutils literal"><span class="pre">raw</span></code></li>
<li><code class="docutils literal"><span class="pre">string</span></code></li>
<li><code class="docutils literal"><span class="pre">timestamp</span></code></li>
</ul>
<p>You can read more about the available MongoDB types on <a class="reference external" href="http://us.php.net/manual/en/mongo.types.php">php.net</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Doctrine mapping types are used to convert the local PHP types to the MongoDB types
when persisting so that your domain is not bound to MongoDB-specific types. For example a
DateTime instance may be converted to MongoDate when you persist your documents, and vice
versa during hydration.</p>
</div>
<p>Generally, the name of each built-in mapping type hints as to how the value will be converted.
This list explains some of the less obvious mapping types:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">bin</span></code>: string to MongoBinData instance with a &quot;generic&quot; type (default)</li>
<li><code class="docutils literal"><span class="pre">bin_bytearray</span></code>: string to MongoBinData instance with a &quot;byte array&quot; type</li>
<li><code class="docutils literal"><span class="pre">bin_custom</span></code>: string to MongoBinData instance with a &quot;custom&quot; type</li>
<li><code class="docutils literal"><span class="pre">bin_func</span></code>: string to MongoBinData instance with a &quot;function&quot; type</li>
<li><code class="docutils literal"><span class="pre">bin_md5</span></code>: string to MongoBinData instance with a &quot;md5&quot; type</li>
<li><code class="docutils literal"><span class="pre">bin_uuid</span></code>: string to MongoBinData instance with a &quot;uuid&quot; type</li>
<li><code class="docutils literal"><span class="pre">collection</span></code>: numerically indexed array to MongoDB array</li>
<li><code class="docutils literal"><span class="pre">date</span></code>: DateTime to MongoDate</li>
<li><code class="docutils literal"><span class="pre">hash</span></code>: associative array to MongoDB object</li>
<li><code class="docutils literal"><span class="pre">id</span></code>: string to MongoId by default, but other formats are possible</li>
<li><code class="docutils literal"><span class="pre">timestamp</span></code>: string to MongoTimestamp</li>
<li><code class="docutils literal"><span class="pre">raw</span></code>: any type</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you are using the hash type, values within the associative array are
passed to MongoDB directly, without being prepared. Only formats suitable for
the Mongo driver should be used. If your hash contains values which are not
suitable you should either use an embedded document or use formats provided
by the MongoDB driver (e.g. <code class="docutils literal"><span class="pre">\MongoDate</span></code> instead of <code class="docutils literal"><span class="pre">\DateTime</span></code>).</p>
</div>
</div>
<div class="section" id="property-mapping">
<h2>Property Mapping<a class="headerlink" href="#property-mapping" title="Permalink to this headline"></a></h2>
<p>After a class has been marked as a document it can specify
mappings for its instance fields. Here we will only look at simple
fields that hold scalar values like strings, numbers, etc.
References to other objects and embedded objects are covered in the
chapter &quot;Reference Mapping&quot;.</p>
<div class="section" id="basic-mapping-identifiers">
<span id="identifiers"></span><h3>Identifiers<a class="headerlink" href="#basic-mapping-identifiers" title="Permalink to this headline"></a></h3>
<p>Every document class needs an identifier. You designate the field
that serves as the identifier with the <code class="docutils literal"><span class="pre">&#64;Id</span></code> marker annotation.
Here is an example:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="sd">/** @Id */</span>
<span class="k">private</span> <span class="nv">$id</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;id&quot;</span> <span class="na">id=</span><span class="s">&quot;true&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">id</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>You can configure custom ID strategies if you don't want to use the default MongoId.
The available strategies are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">AUTO</span></code> - Uses the native generated MongoId.</li>
<li><code class="docutils literal"><span class="pre">ALNUM</span></code> - Generates an alpha-numeric string (based on an incrementing value).</li>
<li><code class="docutils literal"><span class="pre">CUSTOM</span></code> - Defers generation to a AbstractIdGenerator implementation specified in the <code class="docutils literal"><span class="pre">class</span></code> option.</li>
<li><code class="docutils literal"><span class="pre">INCREMENT</span></code> - Uses another collection to auto increment an integer identifier.</li>
<li><code class="docutils literal"><span class="pre">UUID</span></code> - Generates a UUID identifier.</li>
<li><code class="docutils literal"><span class="pre">NONE</span></code> - Do not generate any identifier. ID must be manually set.</li>
</ul>
<p>Here is an example how to manually set a string identifier for your documents:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">MyPersistentClass</span>
<span class="p">{</span>
<span class="sd">/** @Id(strategy=&quot;NONE&quot;, type=&quot;string&quot;) */</span>
<span class="k">private</span> <span class="nv">$id</span><span class="p">;</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">setId</span><span class="p">(</span><span class="nv">$id</span><span class="p">)</span>
<span class="p">{</span>
<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">id</span> <span class="o">=</span> <span class="nv">$id</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;MyPersistentClass&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;field</span> <span class="na">name=</span><span class="s">&quot;id&quot;</span> <span class="na">id=</span><span class="s">&quot;true&quot;</span> <span class="na">strategy=</span><span class="s">&quot;NONE&quot;</span> <span class="na">type=</span><span class="s">&quot;string&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">MyPersistentClass</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">string</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">strategy</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">NONE</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>When using the <code class="docutils literal"><span class="pre">NONE</span></code> strategy you will have to explicitly set an id before persisting the document:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="c1">//...</span>
<span class="nv">$document</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyPersistentClass</span><span class="p">();</span>
<span class="nv">$document</span><span class="o">-&gt;</span><span class="na">setId</span><span class="p">(</span><span class="s1">&#39;my_unique_identifier&#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">$document</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>Now you can retrieve the document later:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="c1">//...</span>
<span class="nv">$document</span> <span class="o">=</span> <span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">find</span><span class="p">(</span><span class="s1">&#39;MyPersistentClass&#39;</span><span class="p">,</span> <span class="s1">&#39;my_unique_identifier&#39;</span><span class="p">);</span>
</pre></div>
</div>
<p>You can define your own ID generator by extending the
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Id\AbstractIdGenerator</span></code> class and specifying the class
as an option for the <code class="docutils literal"><span class="pre">CUSTOM</span></code> strategy:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">MyPersistentClass</span>
<span class="p">{</span>
<span class="sd">/** @Id(strategy=&quot;CUSTOM&quot;, type=&quot;string&quot;, options={&quot;class&quot;=&quot;Vendor\Specific\Generator&quot;}) */</span>
<span class="k">private</span> <span class="nv">$id</span><span class="p">;</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">setId</span><span class="p">(</span><span class="nv">$id</span><span class="p">)</span>
<span class="p">{</span>
<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">id</span> <span class="o">=</span> <span class="nv">$id</span><span class="p">;</span>
<span class="p">}</span>
<span class="c1">//...</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;MyPersistentClass&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;field</span> <span class="na">name=</span><span class="s">&quot;id&quot;</span> <span class="na">id=</span><span class="s">&quot;true&quot;</span> <span class="na">strategy=</span><span class="s">&quot;CUSTOM&quot;</span> <span class="na">type=</span><span class="s">&quot;string&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;id-generator-option</span> <span class="na">name=</span><span class="s">&quot;class&quot;</span> <span class="na">value=</span><span class="s">&quot;Vendor\Specific\Generator&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/field&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">MyPersistentClass</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">strategy</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">CUSTOM</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">string</span>
<span class="l l-Scalar l-Scalar-Plain">options</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">class</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Vendor\Specific\Generator</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
<div class="section" id="fields">
<h3>Fields<a class="headerlink" href="#fields" title="Permalink to this headline"></a></h3>
<p>To mark a property for document persistence the <code class="docutils literal"><span class="pre">&#64;Field</span></code> docblock
annotation can be used. This annotation usually requires at least 1
attribute to be set, the <code class="docutils literal"><span class="pre">type</span></code>. The <code class="docutils literal"><span class="pre">type</span></code> attribute specifies
the Doctrine Mapping Type to use for the field. If the type is not
specified, 'string' is used as the default mapping type since it is
the most flexible.</p>
<p>Example:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><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">/** @Document */</span>
<span class="k">class</span> <span class="nc">User</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="sd">/** @Field(type=&quot;string&quot;) */</span>
<span class="k">private</span> <span class="nv">$username</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
<span class="nt">&lt;doctrine-mongo-mapping</span> <span class="na">xmlns=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping&quot;</span>
<span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span>
<span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping</span>
<span class="s"> http://doctrine-project.org/schemas/odm/doctrine-mongo-mapping.xsd&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;document</span> <span class="na">name=</span><span class="s">&quot;Documents\User&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;id&quot;</span> <span class="na">id=</span><span class="s">&quot;true&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;username&quot;</span> <span class="na">type=</span><span class="s">&quot;string&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/document&gt;</span>
<span class="nt">&lt;/doctrine-mongo-mapping&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">Documents\User</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">fields</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">id</span>
<span class="l l-Scalar l-Scalar-Plain">id</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="l l-Scalar l-Scalar-Plain">username</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">string</span>
</pre></div>
</div>
</li>
</ul>
</div>
<p>In that example we mapped the property <code class="docutils literal"><span class="pre">id</span></code> to the field <code class="docutils literal"><span class="pre">id</span></code>
using the mapping type <code class="docutils literal"><span class="pre">id</span></code> and the property <code class="docutils literal"><span class="pre">name</span></code> is mapped
to the field <code class="docutils literal"><span class="pre">name</span></code> with the default mapping type <code class="docutils literal"><span class="pre">string</span></code>. As
you can see, by default the mongo field names are assumed to be the
same as the property names. To specify a different name for the
field, you can use the <code class="docutils literal"><span class="pre">name</span></code> attribute of the Field annotation
as follows:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/** @Field(name=&quot;db_name&quot;) */</span>
<span class="k">private</span> <span class="nv">$name</span><span class="p">;</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;name&quot;</span> <span class="na">name=</span><span class="s">&quot;db_name&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">db_name</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="custom-mapping-types">
<h2>Custom Mapping Types<a class="headerlink" href="#custom-mapping-types" title="Permalink to this headline"></a></h2>
<p>Doctrine allows you to create new mapping types. This can come in
handy when you're missing a specific mapping type or when you want
to replace the existing implementation of a mapping type.</p>
<p>In order to create a new mapping type you need to subclass
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Types\Type</span></code> and implement/override
the methods. Here is an example skeleton of such a custom type
class:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">namespace</span> <span class="nx">My\Project\Types</span><span class="p">;</span>
<span class="k">use</span> <span class="nx">Doctrine\ODM\MongoDB\Types\Type</span><span class="p">;</span>
<span class="sd">/**</span>
<span class="sd"> * My custom datatype.</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">MyType</span> <span class="k">extends</span> <span class="nx">Type</span>
<span class="p">{</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">convertToPHPValue</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// Note: this function is only called when your custom type is used</span>
<span class="c1">// as an identifier. For other cases, closureToPHP() will be called.</span>
<span class="k">return</span> <span class="k">new</span> <span class="nx">\DateTime</span><span class="p">(</span><span class="s1">&#39;@&#39;</span> <span class="o">.</span> <span class="nv">$value</span><span class="o">-&gt;</span><span class="na">sec</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">closureToPHP</span><span class="p">()</span>
<span class="p">{</span>
<span class="c1">// Return the string body of a PHP closure that will receive $value</span>
<span class="c1">// and store the result of a conversion in a $return variable</span>
<span class="k">return</span> <span class="s1">&#39;$return = new \DateTime($value);&#39;</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">convertToDatabaseValue</span><span class="p">(</span><span class="nv">$value</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// This is called to convert a PHP value to its Mongo equivalent</span>
<span class="k">return</span> <span class="k">new</span> <span class="nx">\MongoDate</span><span class="p">(</span><span class="nv">$value</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Restrictions to keep in mind:</p>
<ul class="simple">
<li>If the value of the field is <em>NULL</em> the method
<code class="docutils literal"><span class="pre">convertToDatabaseValue()</span></code> is not called.</li>
<li>The <code class="docutils literal"><span class="pre">UnitOfWork</span></code> never passes values to the database convert
method that did not change in the request.</li>
</ul>
<p>When you have implemented the type you still need to let Doctrine
know about it. This can be achieved through the
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Types\Type#registerType($name,</span> <span class="pre">$class)</span></code>
method.</p>
<p>Here is an example:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="c1">// in bootstrapping code</span>
<span class="c1">// ...</span>
<span class="k">use</span> <span class="nx">Doctrine\ODM\MongoDB\Types\Type</span><span class="p">;</span>
<span class="c1">// ...</span>
<span class="c1">// Register my type</span>
<span class="nx">Type</span><span class="o">::</span><span class="na">addType</span><span class="p">(</span><span class="s1">&#39;mytype&#39;</span><span class="p">,</span> <span class="s1">&#39;My\Project\Types\MyType&#39;</span><span class="p">);</span>
</pre></div>
</div>
<p>As can be seen above, when registering the custom types in the
configuration you specify a unique name for the mapping type and
map that to the corresponding <a href="#id2"><span class="problematic" id="id3">|FQCN|</span></a>. Now you can use your new
type in your mapping like this:</p>
<div class="configuration-block">
<ul class="simple">
<li><em>PHP</em><div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="k">class</span> <span class="nc">MyPersistentClass</span>
<span class="p">{</span>
<span class="sd">/** @Field(type=&quot;mytype&quot;) */</span>
<span class="k">private</span> <span class="nv">$field</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><em>XML</em><div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;field</span> <span class="na">fieldName=</span><span class="s">&quot;field&quot;</span> <span class="na">type=</span><span class="s">&quot;mytype&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
</div>
</li>
<li><em>YAML</em><div class="highlight-yaml"><div class="highlight"><pre><span class="l l-Scalar l-Scalar-Plain">field</span><span class="p p-Indicator">:</span>
<span class="l l-Scalar l-Scalar-Plain">type</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">mytype</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
<div class="section" id="multiple-document-types-in-a-collection">
<h2>Multiple Document Types in a Collection<a class="headerlink" href="#multiple-document-types-in-a-collection" title="Permalink to this headline"></a></h2>
<p>You can easily store multiple types of documents in a single collection. This
requires specifying the same collection name, <code class="docutils literal"><span class="pre">discriminatorField</span></code>, and
(optionally) <code class="docutils literal"><span class="pre">discriminatorMap</span></code> mapping options for each class that will share
the collection. Here is an example:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="sd">/**</span>
<span class="sd"> * @Document(collection=&quot;my_documents&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> * @DiscriminatorMap({&quot;article&quot;=&quot;Article&quot;, &quot;album&quot;=&quot;Album&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Article</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
<span class="sd">/**</span>
<span class="sd"> * @Document(collection=&quot;my_documents&quot;)</span>
<span class="sd"> * @DiscriminatorField(&quot;type&quot;)</span>
<span class="sd"> * @DiscriminatorMap({&quot;article&quot;=&quot;Article&quot;, &quot;album&quot;=&quot;Album&quot;})</span>
<span class="sd"> */</span>
<span class="k">class</span> <span class="nc">Album</span>
<span class="p">{</span>
<span class="c1">// ...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>All instances of <code class="docutils literal"><span class="pre">Article</span></code> and <code class="docutils literal"><span class="pre">Album</span></code> will be stored in the
<code class="docutils literal"><span class="pre">my_documents</span></code> collection. You can query for the documents of a particular
class just like you normally would and the results will automatically be limited
based on the discriminator value for that class.</p>
<p>If you wish to query for multiple types of documents from the collection, you
may pass an array of document class names when creating a query builder:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp">&lt;?php</span>
<span class="nv">$query</span> <span class="o">=</span> <span class="nv">$dm</span><span class="o">-&gt;</span><span class="na">createQuery</span><span class="p">(</span><span class="k">array</span><span class="p">(</span><span class="s1">&#39;Article&#39;</span><span class="p">,</span> <span class="s1">&#39;Album&#39;</span><span class="p">));</span>
<span class="nv">$documents</span> <span class="o">=</span> <span class="nv">$query</span><span class="o">-&gt;</span><span class="na">execute</span><span class="p">();</span>
</pre></div>
</div>
<p>The above will return a cursor that will allow you to iterate over all
<code class="docutils literal"><span class="pre">Article</span></code> and <code class="docutils literal"><span class="pre">Album</span></code> documents in the collections.</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="#">Basic Mapping</a><ul>
<li><a class="reference internal" href="#mapping-drivers">Mapping Drivers</a></li>
<li><a class="reference internal" href="#introduction-to-docblock-annotations">Introduction to Docblock Annotations</a></li>
<li><a class="reference internal" href="#persistent-classes">Persistent classes</a></li>
<li><a class="reference internal" href="#doctrine-mapping-types">Doctrine Mapping Types</a></li>
<li><a class="reference internal" href="#property-mapping">Property Mapping</a><ul>
<li><a class="reference internal" href="#basic-mapping-identifiers">Identifiers</a></li>
<li><a class="reference internal" href="#fields">Fields</a></li>
</ul>
</li>
<li><a class="reference internal" href="#custom-mapping-types">Custom Mapping Types</a></li>
<li><a class="reference internal" href="#multiple-document-types-in-a-collection">Multiple Document Types in a Collection</a></li>
</ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/basic-mapping.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