326 lines
19 KiB
HTML
326 lines
19 KiB
HTML
|
<!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>Metadata Drivers — 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> »</li>
|
||
|
|
<li><a href="../index.html">Doctrine MongoDB ODM 1.1.5 documentation</a> »</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="document">
|
||
|
|
<div class="documentwrapper">
|
||
|
|
<div class="bodywrapper">
|
||
|
|
|
||
|
|
<div class="body" >
|
||
|
|
|
||
|
|
<div class="section" id="metadata-drivers">
|
||
|
|
<h1>Metadata Drivers<a class="headerlink" href="#metadata-drivers" title="Permalink to this headline">¶</a></h1>
|
||
|
|
<p>The heart of an object mapper is the mapping information
|
||
|
|
that glues everything together. It instructs the DocumentManager how
|
||
|
|
it should behave when dealing with the different documents.</p>
|
||
|
|
<div class="section" id="core-metadata-drivers">
|
||
|
|
<h2>Core Metadata Drivers<a class="headerlink" href="#core-metadata-drivers" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>Doctrine provides a few different ways for you to specify your
|
||
|
|
metadata:</p>
|
||
|
|
<ul class="simple">
|
||
|
|
<li><strong>XML files</strong> (XmlDriver)</li>
|
||
|
|
<li><strong>Class DocBlock Annotations</strong> (AnnotationDriver)</li>
|
||
|
|
<li><strong>YAML files</strong> (YamlDriver)</li>
|
||
|
|
<li><strong>PHP Code in files or static functions</strong> (PhpDriver)</li>
|
||
|
|
</ul>
|
||
|
|
<p>Something important to note about the above drivers is they are all
|
||
|
|
an intermediate step to the same end result. The mapping
|
||
|
|
information is populated to <code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Mapping\ClassMetadata</span></code>
|
||
|
|
instances. So in the end, Doctrine only ever has to work with the
|
||
|
|
API of the <code class="docutils literal"><span class="pre">ClassMetadata</span></code> class to get mapping information for
|
||
|
|
a document.</p>
|
||
|
|
<div class="admonition note">
|
||
|
|
<p class="first admonition-title">Note</p>
|
||
|
|
<p>The populated <code class="docutils literal"><span class="pre">ClassMetadata</span></code> instances are also cached
|
||
|
|
so in a production environment the parsing and populating only ever
|
||
|
|
happens once. You can configure the metadata cache implementation
|
||
|
|
using the <code class="docutils literal"><span class="pre">setMetadataCacheImpl()</span></code> method on the
|
||
|
|
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Configuration</span></code> class:</p>
|
||
|
|
<div class="last highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="nv">$em</span><span class="o">-></span><span class="na">getConfiguration</span><span class="p">()</span><span class="o">-></span><span class="na">setMetadataCacheImpl</span><span class="p">(</span><span class="k">new</span> <span class="nx">ApcCache</span><span class="p">());</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<p>If you want to use one of the included core metadata drivers you
|
||
|
|
just need to configure it. All the drivers are in the
|
||
|
|
<code class="docutils literal"><span class="pre">Doctrine\ODM\MongoDB\Mapping\Driver</span></code> namespace:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="nv">$driver</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">\Doctrine\ODM\MongoDB\Mapping\Driver\XmlDriver</span><span class="p">(</span><span class="s1">'/path/to/mapping/files'</span><span class="p">);</span>
|
||
|
|
<span class="nv">$em</span><span class="o">-></span><span class="na">getConfiguration</span><span class="p">()</span><span class="o">-></span><span class="na">setMetadataDriverImpl</span><span class="p">(</span><span class="nv">$driver</span><span class="p">);</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="implementing-metadata-drivers">
|
||
|
|
<h2>Implementing Metadata Drivers<a class="headerlink" href="#implementing-metadata-drivers" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>In addition to the included metadata drivers you can very easily
|
||
|
|
implement your own. All you need to do is define a class which
|
||
|
|
implements the <code class="docutils literal"><span class="pre">Driver</span></code> interface:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="k">namespace</span> <span class="nx">Doctrine\ODM\MongoDB\Mapping\Driver</span><span class="p">;</span>
|
||
|
|
|
||
|
|
<span class="k">use</span> <span class="nx">Doctrine\ODM\MongoDB\Mapping\ClassMetadataInfo</span><span class="p">;</span>
|
||
|
|
|
||
|
|
<span class="k">interface</span> <span class="nx">Driver</span>
|
||
|
|
<span class="p">{</span>
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * Loads the metadata for the specified class into the provided container.</span>
|
||
|
|
<span class="sd"> *</span>
|
||
|
|
<span class="sd"> * @param string $className</span>
|
||
|
|
<span class="sd"> * @param ClassMetadataInfo $metadata</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">function</span> <span class="nf">loadMetadataForClass</span><span class="p">(</span><span class="nv">$className</span><span class="p">,</span> <span class="nx">ClassMetadataInfo</span> <span class="nv">$metadata</span><span class="p">);</span>
|
||
|
|
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * Gets the names of all mapped classes known to this driver.</span>
|
||
|
|
<span class="sd"> *</span>
|
||
|
|
<span class="sd"> * @return array The names of all mapped classes known to this driver.</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">function</span> <span class="nf">getAllClassNames</span><span class="p">();</span>
|
||
|
|
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * Whether the class with the specified name should have its metadata loaded.</span>
|
||
|
|
<span class="sd"> * This is only the case if it is either mapped as a Document or a</span>
|
||
|
|
<span class="sd"> * MappedSuperclass.</span>
|
||
|
|
<span class="sd"> *</span>
|
||
|
|
<span class="sd"> * @param string $className</span>
|
||
|
|
<span class="sd"> * @return boolean</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">function</span> <span class="nf">isTransient</span><span class="p">(</span><span class="nv">$className</span><span class="p">);</span>
|
||
|
|
<span class="p">}</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>If you want to write a metadata driver to parse information from
|
||
|
|
some file format we've made your life a little easier by providing
|
||
|
|
the <code class="docutils literal"><span class="pre">AbstractFileDriver</span></code> implementation for you to extend from:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="k">class</span> <span class="nc">MyMetadataDriver</span> <span class="k">extends</span> <span class="nx">AbstractFileDriver</span>
|
||
|
|
<span class="p">{</span>
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * {@inheritdoc}</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">protected</span> <span class="nv">$_fileExtension</span> <span class="o">=</span> <span class="s1">'.dcm.ext'</span><span class="p">;</span>
|
||
|
|
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * {@inheritdoc}</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">public</span> <span class="k">function</span> <span class="nf">loadMetadataForClass</span><span class="p">(</span><span class="nv">$className</span><span class="p">,</span> <span class="nx">ClassMetadataInfo</span> <span class="nv">$metadata</span><span class="p">)</span>
|
||
|
|
<span class="p">{</span>
|
||
|
|
<span class="nv">$data</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-></span><span class="na">_loadMappingFile</span><span class="p">(</span><span class="nv">$file</span><span class="p">);</span>
|
||
|
|
|
||
|
|
<span class="c1">// populate ClassMetadataInfo instance from $data</span>
|
||
|
|
<span class="p">}</span>
|
||
|
|
|
||
|
|
<span class="sd">/**</span>
|
||
|
|
<span class="sd"> * {@inheritdoc}</span>
|
||
|
|
<span class="sd"> */</span>
|
||
|
|
<span class="k">protected</span> <span class="k">function</span> <span class="nf">_loadMappingFile</span><span class="p">(</span><span class="nv">$file</span><span class="p">)</span>
|
||
|
|
<span class="p">{</span>
|
||
|
|
<span class="c1">// parse contents of $file and return php data structure</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">When using the <code class="docutils literal"><span class="pre">AbstractFileDriver</span></code> it requires that you
|
||
|
|
only have one document defined per file and the file named after the
|
||
|
|
class described inside where namespace separators are replaced by
|
||
|
|
periods. So if you have a document named <code class="docutils literal"><span class="pre">Documents\User</span></code> and you
|
||
|
|
wanted to write a mapping file for your driver above you would need
|
||
|
|
to name the file <code class="docutils literal"><span class="pre">Documents.User.dcm.ext</span></code> for it to be
|
||
|
|
recognized.</p>
|
||
|
|
</div>
|
||
|
|
<p>Now you can use your <code class="docutils literal"><span class="pre">MyMetadataDriver</span></code> implementation by setting
|
||
|
|
it with the <code class="docutils literal"><span class="pre">setMetadataDriverImpl()</span></code> method:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="nv">$driver</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MyMetadataDriver</span><span class="p">(</span><span class="s1">'/path/to/mapping/files'</span><span class="p">);</span>
|
||
|
|
<span class="nv">$em</span><span class="o">-></span><span class="na">getConfiguration</span><span class="p">()</span><span class="o">-></span><span class="na">setMetadataDriverImpl</span><span class="p">(</span><span class="nv">$driver</span><span class="p">);</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="classmetadata">
|
||
|
|
<h2>ClassMetadata<a class="headerlink" href="#classmetadata" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>The last piece you need to know and understand about metadata in
|
||
|
|
Doctrine is the API of the <code class="docutils literal"><span class="pre">ClassMetadata</span></code> classes. You need to
|
||
|
|
be familiar with them in order to implement your own drivers but
|
||
|
|
more importantly to retrieve mapping information for a certain
|
||
|
|
document when needed.</p>
|
||
|
|
<p>You have all the methods you need to manually specify the mapping
|
||
|
|
information instead of using some mapping file to populate it from.
|
||
|
|
The base <code class="docutils literal"><span class="pre">ClassMetadataInfo</span></code> class is responsible for only data
|
||
|
|
storage and is not meant for runtime use. It does not require that
|
||
|
|
the class actually exists yet so it is useful for describing some
|
||
|
|
document before it exists and using that information to generate for
|
||
|
|
example the documents themselves. The class <code class="docutils literal"><span class="pre">ClassMetadata</span></code>
|
||
|
|
extends <code class="docutils literal"><span class="pre">ClassMetadataInfo</span></code> and adds some functionality required
|
||
|
|
for runtime usage and requires that the PHP class is present and
|
||
|
|
can be autoloaded.</p>
|
||
|
|
<p>You can read more about the API of the <code class="docutils literal"><span class="pre">ClassMetadata</span></code> classes in
|
||
|
|
the PHP Mapping chapter.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="getting-classmetadata-instances">
|
||
|
|
<h2>Getting ClassMetadata Instances<a class="headerlink" href="#getting-classmetadata-instances" title="Permalink to this headline">¶</a></h2>
|
||
|
|
<p>If you want to get the <code class="docutils literal"><span class="pre">ClassMetadata</span></code> instance for a document in
|
||
|
|
your project to programmatically use some mapping information to
|
||
|
|
generate some HTML or something similar you can retrieve it through
|
||
|
|
the <code class="docutils literal"><span class="pre">ClassMetadataFactory</span></code>:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="nv">$cmf</span> <span class="o">=</span> <span class="nv">$em</span><span class="o">-></span><span class="na">getMetadataFactory</span><span class="p">();</span>
|
||
|
|
<span class="nv">$class</span> <span class="o">=</span> <span class="nv">$cmf</span><span class="o">-></span><span class="na">getMetadataFor</span><span class="p">(</span><span class="s1">'MyDocumentName'</span><span class="p">);</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
<p>Now you can learn about the document and use the data stored in the
|
||
|
|
<code class="docutils literal"><span class="pre">ClassMetadata</span></code> instance to get all mapped fields for example and
|
||
|
|
iterate over them:</p>
|
||
|
|
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
|
||
|
|
|
||
|
|
<span class="k">foreach</span> <span class="p">(</span><span class="nv">$class</span><span class="o">-></span><span class="na">fieldMappings</span> <span class="k">as</span> <span class="nv">$fieldMapping</span><span class="p">)</span> <span class="p">{</span>
|
||
|
|
<span class="k">echo</span> <span class="nv">$fieldMapping</span><span class="p">[</span><span class="s1">'fieldName'</span><span class="p">]</span> <span class="o">.</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">;</span>
|
||
|
|
<span class="p">}</span>
|
||
|
|
</pre></div>
|
||
|
|
</div>
|
||
|
|
</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="#">Metadata Drivers</a><ul>
|
||
|
|
<li><a class="reference internal" href="#core-metadata-drivers">Core Metadata Drivers</a></li>
|
||
|
|
<li><a class="reference internal" href="#implementing-metadata-drivers">Implementing Metadata Drivers</a></li>
|
||
|
|
<li><a class="reference internal" href="#classmetadata">ClassMetadata</a></li>
|
||
|
|
<li><a class="reference internal" href="#getting-classmetadata-instances">Getting ClassMetadata Instances</a></li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3>This Page</h3>
|
||
|
|
<ul class="this-page-menu">
|
||
|
|
<li><a href="../_sources/reference/metadata-drivers.rst.txt"
|
||
|
|
rel="nofollow">Show Source</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="clearer"></div>
|
||
|
|
</div>
|
||
|
|
<div class="footer">
|
||
|
|
© 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>
|