/usr/share/doc/php-doctrine-orm/html/reference/metadata-drivers.html is in doctrine-orm-doc 2.4.6-1+deb8u1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 | <!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>27. Metadata Drivers — Doctrine 2 ORM 2 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: '2',
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="top" title="Doctrine 2 ORM 2 documentation" href="../index.html" />
<link rel="next" title="28. Best Practices" href="best-practices.html" />
<link rel="prev" title="26. Tools" href="tools.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="/">home</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/about">about</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/projects.html">projects</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/projects/orm">orm</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/projects/dbal">dbal</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/blog">blog</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/jira">development</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/contribute">contribute</a></li>
<li><a class="" target="_top" href="http://www.doctrine-project.org/community">community</a></li>
</ul>
</div>
</div>
<div id="content" class="cls">
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="best-practices.html" title="28. Best Practices"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tools.html" title="26. Tools"
accesskey="P">previous</a> |</li>
<li><a href="/">Doctrine Homepage</a> »</li>
<li><a href="../index.html">Doctrine 2 ORM 2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" >
<div class="section" id="metadata-drivers">
<h1>27. Metadata Drivers<a class="headerlink" href="#metadata-drivers" title="Permalink to this headline">¶</a></h1>
<p>The heart of an object relational mapper is the mapping information
that glues everything together. It instructs the EntityManager how
it should behave when dealing with the different entities.</p>
<div class="section" id="core-metadata-drivers">
<h2>27.1. 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 <tt class="docutils literal"><span class="pre">Doctrine\ORM\Mapping\ClassMetadata</span></tt>
instances. So in the end, Doctrine only ever has to work with the
API of the <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> class to get mapping information for
an entity.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The populated <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> 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 <tt class="docutils literal"><span class="pre">setMetadataCacheImpl()</span></tt> method on the
<tt class="docutils literal"><span class="pre">Doctrine\ORM\Configuration</span></tt> 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
<tt class="docutils literal"><span class="pre">Doctrine\ORM\Mapping\Driver</span></tt> 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\ORM\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>27.2. 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 <tt class="docutils literal"><span class="pre">Driver</span></tt> interface:</p>
<div class="highlight-php"><div class="highlight"><pre><span class="cp"><?php</span>
<span class="k">namespace</span> <span class="nx">Doctrine\ORM\Mapping\Driver</span><span class="p">;</span>
<span class="k">use</span> <span class="nx">Doctrine\ORM\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 an Entity 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 <tt class="docutils literal"><span class="pre">AbstractFileDriver</span></tt> 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 <tt class="docutils literal"><span class="pre">AbstractFileDriver</span></tt> it requires that you
only have one entity defined per file and the file named after the
class described inside where namespace separators are replaced by
periods. So if you have an entity named <tt class="docutils literal"><span class="pre">Entities\User</span></tt> and you
wanted to write a mapping file for your driver above you would need
to name the file <tt class="docutils literal"><span class="pre">Entities.User.dcm.ext</span></tt> for it to be
recognized.</p>
</div>
<p>Now you can use your <tt class="docutils literal"><span class="pre">MyMetadataDriver</span></tt> implementation by setting
it with the <tt class="docutils literal"><span class="pre">setMetadataDriverImpl()</span></tt> 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>27.3. 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 2 is the API of the <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> 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
entity 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 <tt class="docutils literal"><span class="pre">ClassMetadataInfo</span></tt> 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
entity before it exists and using that information to generate for
example the entities themselves. The class <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt>
extends <tt class="docutils literal"><span class="pre">ClassMetadataInfo</span></tt> 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 <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> classes in
the PHP Mapping chapter.</p>
</div>
<div class="section" id="getting-classmetadata-instances">
<h2>27.4. Getting ClassMetadata Instances<a class="headerlink" href="#getting-classmetadata-instances" title="Permalink to this headline">¶</a></h2>
<p>If you want to get the <tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> instance for an entity in
your project to programmatically use some mapping information to
generate some HTML or something similar you can retrieve it through
the <tt class="docutils literal"><span class="pre">ClassMetadataFactory</span></tt>:</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">'MyEntityName'</span><span class="p">);</span>
</pre></div>
</div>
<p>Now you can learn about the entity and use the data stored in the
<tt class="docutils literal"><span class="pre">ClassMetadata</span></tt> 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="#">27. Metadata Drivers</a><ul>
<li><a class="reference internal" href="#core-metadata-drivers">27.1. Core Metadata Drivers</a></li>
<li><a class="reference internal" href="#implementing-metadata-drivers">27.2. Implementing Metadata Drivers</a></li>
<li><a class="reference internal" href="#classmetadata">27.3. ClassMetadata</a></li>
<li><a class="reference internal" href="#getting-classmetadata-instances">27.4. Getting ClassMetadata Instances</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="tools.html"
title="previous chapter">26. Tools</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="best-practices.html"
title="next chapter">28. Best Practices</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/metadata-drivers.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2010-12, Doctrine Project Team.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.3.
<br/>
<a target="_BLANK" href="http://www.servergrove.com"><img src="../_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="Submit" value="Donate via PayPal" />
</form>
</div>
</div>
<div id="bot-rcnr">
<div class="tl"><!-- corner --></div>
</div>
</div>
<a class="githublink" href="http://github.com/doctrine">Fork me on GitHub</a>
</body>
</html>
|