Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 479 lines (352 sloc) 16.587 kb
a5a0dfa @beberlei Converted ORM Docs into ReST
beberlei authored
1 Configuration
2 =============
3
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
4 Bootstrapping
5 -------------
6
7 Bootstrapping Doctrine is a relatively simple procedure that
8 roughly exists of just 2 steps:
9
10
11 - Making sure Doctrine class files can be loaded on demand.
12 - Obtaining an EntityManager instance.
13
14 Class loading
15 ~~~~~~~~~~~~~
16
17 Lets start with the class loading setup. We need to set up some
18 class loaders (often called "autoloader") so that Doctrine class
19 files are loaded on demand. The Doctrine namespace contains a very
20 fast and minimalistic class loader that can be used for Doctrine
21 and any other libraries where the coding standards ensure that a
22 class's location in the directory tree is reflected by its name and
23 namespace and where there is a common root namespace.
24
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
25 .. note::
26
27 You are not forced to use the Doctrine class loader to
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
28 load Doctrine classes. Doctrine does not care how the classes are
29 loaded, if you want to use a different class loader or your own to
30 load Doctrine classes, just do that. Along the same lines, the
31 class loader in the Doctrine namespace is not meant to be only used
32 for Doctrine classes, too. It is a generic class loader that can be
33 used for any classes that follow some basic naming standards as
34 described above.
35
36
37 The following example shows the setup of a ``ClassLoader`` for the
38 different types of Doctrine Installations:
39
a5a0dfa @beberlei Converted ORM Docs into ReST
beberlei authored
40 .. note::
41
42 This assumes you've created some kind of script to test
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
43 the following code in. Something like a ``test.php`` file.
44
45
46 PEAR or Tarball Download
47 ^^^^^^^^^^^^^^^^^^^^^^^^
48
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
49 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
50
51 <?php
52 // test.php
53
54 require '/path/to/libraries/Doctrine/Common/ClassLoader.php';
55 $classLoader = new \Doctrine\Common\ClassLoader('Doctrine', '/path/to/libraries');
56 $classLoader->register(); // register on SPL autoload stack
57
58 Git
59 ^^^
60
61 The Git bootstrap assumes that you have fetched the related
62 packages through ``git submodule update --init``
63
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
64 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
65
66 <?php
67 // test.php
68
69 $lib = '/path/to/doctrine2-orm/lib/';
70 require $lib . 'vendor/doctrine-common/lib/Doctrine/Common/ClassLoader.php';
71
72 $classLoader = new \Doctrine\Common\ClassLoader('Doctrine\Common', $lib . 'vendor/doctrine-common/lib');
73 $classLoader->register();
74
75 $classLoader = new \Doctrine\Common\ClassLoader('Doctrine\DBAL', $lib . 'vendor/doctrine-dbal/lib');
76 $classLoader->register();
77
78 $classLoader = new \Doctrine\Common\ClassLoader('Doctrine\ORM', $lib);
79 $classLoader->register();
80
81 Additional Symfony Components
82 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83
84 If you don't use Doctrine2 in combination with Symfony2 you have to
85 register an additional namespace to be able to use the Doctrine-CLI
86 Tool or the YAML Mapping driver:
87
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
88 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
89
90 <?php
91 // PEAR or Tarball setup
92 $classloader = new \Doctrine\Common\ClassLoader('Symfony', '/path/to/libraries/Doctrine');
93 $classloader->register();
94
95 // Git Setup
96 $classloader = new \Doctrine\Common\ClassLoader('Symfony', $lib . 'vendor/');
97 $classloader->register();
98
99 For best class loading performance it is recommended that you keep
100 your include\_path short, ideally it should only contain the path
101 to the PEAR libraries, and any other class libraries should be
102 registered with their full base path.
103
104 Obtaining an EntityManager
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~
106
107 Once you have prepared the class loading, you acquire an
108 *EntityManager* instance. The EntityManager class is the primary
109 access point to ORM functionality provided by Doctrine.
110
111 A simple configuration of the EntityManager requires a
112 ``Doctrine\ORM\Configuration`` instance as well as some database
113 connection parameters:
114
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
115 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
116
117 <?php
118 use Doctrine\ORM\EntityManager,
119 Doctrine\ORM\Configuration;
120
121 // ...
122
123 if ($applicationMode == "development") {
124 $cache = new \Doctrine\Common\Cache\ArrayCache;
125 } else {
126 $cache = new \Doctrine\Common\Cache\ApcCache;
127 }
128
129 $config = new Configuration;
130 $config->setMetadataCacheImpl($cache);
131 $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
132 $config->setMetadataDriverImpl($driverImpl);
133 $config->setQueryCacheImpl($cache);
134 $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
135 $config->setProxyNamespace('MyProject\Proxies');
136
137 if ($applicationMode == "development") {
138 $config->setAutoGenerateProxyClasses(true);
139 } else {
140 $config->setAutoGenerateProxyClasses(false);
141 }
142
143 $connectionOptions = array(
144 'driver' => 'pdo_sqlite',
145 'path' => 'database.sqlite'
146 );
147
148 $em = EntityManager::create($connectionOptions, $config);
149
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
150 .. note::
151
152 Do not use Doctrine without a metadata and query cache!
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
153 Doctrine is highly optimized for working with caches. The main
154 parts in Doctrine that are optimized for caching are the metadata
155 mapping information with the metadata cache and the DQL to SQL
156 conversions with the query cache. These 2 caches require only an
157 absolute minimum of memory yet they heavily improve the runtime
158 performance of Doctrine. The recommended cache driver to use with
159 Doctrine is `APC <http://www.php.net/apc>`_. APC provides you with
160 an opcode-cache (which is highly recommended anyway) and a very
161 fast in-memory cache storage that you can use for the metadata and
162 query caches as seen in the previous code snippet.
163
164
165 Configuration Options
166 ---------------------
167
168 The following sections describe all the configuration options
169 available on a ``Doctrine\ORM\Configuration`` instance.
170
171 Proxy Directory (***REQUIRED***)
172 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
173
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
174 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
175
176 <?php
177 $config->setProxyDir($dir);
178 $config->getProxyDir();
179
180 Gets or sets the directory where Doctrine generates any proxy
181 classes. For a detailed explanation on proxy classes and how they
182 are used in Doctrine, refer to the "Proxy Objects" section further
183 down.
184
185 Proxy Namespace (***REQUIRED***)
186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
188 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
189
190 <?php
191 $config->setProxyNamespace($namespace);
192 $config->getProxyNamespace();
193
194 Gets or sets the namespace to use for generated proxy classes. For
195 a detailed explanation on proxy classes and how they are used in
196 Doctrine, refer to the "Proxy Objects" section further down.
197
198 Metadata Driver (***REQUIRED***)
199 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
200
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
201 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
202
203 <?php
204 $config->setMetadataDriverImpl($driver);
205 $config->getMetadataDriverImpl();
206
207 Gets or sets the metadata driver implementation that is used by
208 Doctrine to acquire the object-relational metadata for your
209 classes.
210
211 There are currently 4 available implementations:
212
213
214 - ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
215 - ``Doctrine\ORM\Mapping\Driver\XmlDriver``
216 - ``Doctrine\ORM\Mapping\Driver\YamlDriver``
217 - ``Doctrine\ORM\Mapping\Driver\DriverChain``
218
219 Throughout the most part of this manual the AnnotationDriver is
220 used in the examples. For information on the usage of the XmlDriver
221 or YamlDriver please refer to the dedicated chapters
222 ``XML Mapping`` and ``YAML Mapping``.
223
224 The annotation driver can be configured with a factory method on
225 the ``Doctrine\ORM\Configuration``:
226
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
227 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
228
229 <?php
230 $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
231 $config->setMetadataDriverImpl($driverImpl);
232
233 The path information to the entities is required for the annotation
234 driver, because otherwise mass-operations on all entities through
235 the console could not work correctly. All of metadata drivers
236 accept either a single directory as a string or an array of
237 directories. With this feature a single driver can support multiple
238 directories of Entities.
239
240 Metadata Cache (***RECOMMENDED***)
241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
243 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
244
245 <?php
246 $config->setMetadataCacheImpl($cache);
247 $config->getMetadataCacheImpl();
248
249 Gets or sets the cache implementation to use for caching metadata
250 information, that is, all the information you supply via
251 annotations, xml or yaml, so that they do not need to be parsed and
252 loaded from scratch on every single request which is a waste of
253 resources. The cache implementation must implement the
254 ``Doctrine\Common\Cache\Cache`` interface.
255
256 Usage of a metadata cache is highly recommended.
257
258 The recommended implementations for production are:
259
260
261 - ``Doctrine\Common\Cache\ApcCache``
262 - ``Doctrine\Common\Cache\MemcacheCache``
263 - ``Doctrine\Common\Cache\XcacheCache``
264
265 For development you should use the
266 ``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
267 per-request basis.
268
269 Query Cache (***RECOMMENDED***)
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
272 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
273
274 <?php
275 $config->setQueryCacheImpl($cache);
276 $config->getQueryCacheImpl();
277
278 Gets or sets the cache implementation to use for caching DQL
279 queries, that is, the result of a DQL parsing process that includes
280 the final SQL as well as meta information about how to process the
281 SQL result set of a query. Note that the query cache does not
282 affect query results. You do not get stale data. This is a pure
283 optimization cache without any negative side-effects (except some
284 minimal memory usage in your cache).
285
286 Usage of a query cache is highly recommended.
287
288 The recommended implementations for production are:
289
290
291 - ``Doctrine\Common\Cache\ApcCache``
292 - ``Doctrine\Common\Cache\MemcacheCache``
293 - ``Doctrine\Common\Cache\XcacheCache``
294
295 For development you should use the
296 ``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
297 per-request basis.
298
299 SQL Logger (***Optional***)
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
301
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
302 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
303
304 <?php
305 $config->setSQLLogger($logger);
306 $config->getSQLLogger();
307
308 Gets or sets the logger to use for logging all SQL statements
309 executed by Doctrine. The logger class must implement the
7d42497 @beberlei Fix typo with SQLLogger in configuration.rst
beberlei authored
310 ``Doctrine\DBAL\Logging\SQLLogger`` interface. A simple default
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
311 implementation that logs to the standard output using ``echo`` and
312 ``var_dump`` can be found at
7d42497 @beberlei Fix typo with SQLLogger in configuration.rst
beberlei authored
313 ``Doctrine\DBAL\Logging\EchoSQLLogger``.
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
314
315 Auto-generating Proxy Classes (***OPTIONAL***)
316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
318 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
319
320 <?php
321 $config->setAutoGenerateProxyClasses($bool);
322 $config->getAutoGenerateProxyClasses();
323
324 Gets or sets whether proxy classes should be generated
325 automatically at runtime by Doctrine. If set to ``FALSE``, proxy
326 classes must be generated manually through the doctrine command
327 line task ``generate-proxies``. The strongly recommended value for
328 a production environment is ``FALSE``.
329
330 Development vs Production Configuration
331 ---------------------------------------
332
333 You should code your Doctrine2 bootstrapping with two different
334 runtime models in mind. There are some serious benefits of using
335 APC or Memcache in production. In development however this will
336 frequently give you fatal errors, when you change your entities and
337 the cache still keeps the outdated metadata. That is why we
338 recommend the ``ArrayCache`` for development.
339
340 Furthermore you should have the Auto-generating Proxy Classes
341 option to true in development and to false in production. If this
342 option is set to ``TRUE`` it can seriously hurt your script
343 performance if several proxy classes are re-generated during script
344 execution. Filesystem calls of that magnitude can even slower than
345 all the database queries Doctrine issues. Additionally writing a
346 proxy sets an exclusive file lock which can cause serious
347 performance bottlenecks in systems with regular concurrent
348 requests.
349
350 Connection Options
351 ------------------
352
353 The ``$connectionOptions`` passed as the first argument to
354 ``EntityManager::create()`` has to be either an array or an
355 instance of ``Doctrine\DBAL\Connection``. If an array is passed it
356 is directly passed along to the DBAL Factory
357 ``Doctrine\DBAL\DriverManager::getConnection()``. The DBAL
358 configuration is explained in the
359 `DBAL section <./../../../../../dbal/2.0/docs/reference/configuration/en>`_.
360
361 Proxy Objects
362 -------------
363
364 A proxy object is an object that is put in place or used instead of
365 the "real" object. A proxy object can add behavior to the object
366 being proxied without that object being aware of it. In Doctrine 2,
367 proxy objects are used to realize several features but mainly for
368 transparent lazy-loading.
369
370 Proxy objects with their lazy-loading facilities help to keep the
371 subset of objects that are already in memory connected to the rest
372 of the objects. This is an essential property as without it there
373 would always be fragile partial objects at the outer edges of your
374 object graph.
375
376 Doctrine 2 implements a variant of the proxy pattern where it
377 generates classes that extend your entity classes and adds
378 lazy-loading capabilities to them. Doctrine can then give you an
379 instance of such a proxy class whenever you request an object of
380 the class being proxied. This happens in two situations:
381
a5a0dfa @beberlei Converted ORM Docs into ReST
beberlei authored
382 Reference Proxies
383 ~~~~~~~~~~~~~~~~~
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
384
385 The method ``EntityManager#getReference($entityName, $identifier)``
386 lets you obtain a reference to an entity for which the identifier
387 is known, without loading that entity from the database. This is
388 useful, for example, as a performance enhancement, when you want to
389 establish an association to an entity for which you have the
390 identifier. You could simply do this:
391
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
392 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
393
394 <?php
395 // $em instanceof EntityManager, $cart instanceof MyProject\Model\Cart
396 // $itemId comes from somewhere, probably a request parameter
397 $item = $em->getReference('MyProject\Model\Item', $itemId);
398 $cart->addItem($item);
399
400 Here, we added an Item to a Cart without loading the Item from the
401 database. If you invoke any method on the Item instance, it would
402 fully initialize its state transparently from the database. Here
403 $item is actually an instance of the proxy class that was generated
404 for the Item class but your code does not need to care. In fact it
405 **should not care**. Proxy objects should be transparent to your
406 code.
407
a5a0dfa @beberlei Converted ORM Docs into ReST
beberlei authored
408 Association proxies
409 ~~~~~~~~~~~~~~~~~~~
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
410
411 The second most important situation where Doctrine uses proxy
412 objects is when querying for objects. Whenever you query for an
413 object that has a single-valued association to another object that
414 is configured LAZY, without joining that association in the same
415 query, Doctrine puts proxy objects in place where normally the
416 associated object would be. Just like other proxies it will
417 transparently initialize itself on first access.
418
a5a0dfa @beberlei Converted ORM Docs into ReST
beberlei authored
419 .. note::
420
421 Joining an association in a DQL or native query
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
422 essentially means eager loading of that association in that query.
423 This will override the 'fetch' option specified in the mapping for
424 that association, but only for that query.
425
426
427 Generating Proxy classes
428 ~~~~~~~~~~~~~~~~~~~~~~~~
429
430 Proxy classes can either be generated manually through the Doctrine
431 Console or automatically by Doctrine. The configuration option that
432 controls this behavior is:
433
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
434 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
435
436 <?php
437 $config->setAutoGenerateProxyClasses($bool);
438 $config->getAutoGenerateProxyClasses();
439
440 The default value is ``TRUE`` for convenient development. However,
441 this setting is not optimal for performance and therefore not
442 recommended for a production environment. To eliminate the overhead
443 of proxy class generation during runtime, set this configuration
444 option to ``FALSE``. When you do this in a development environment,
445 note that you may get class/file not found errors if certain proxy
446 classes are not available or failing lazy-loads if new methods were
447 added to the entity class that are not yet in the proxy class. In
448 such a case, simply use the Doctrine Console to (re)generate the
449 proxy classes like so:
450
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
451 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
452
453 $ ./doctrine orm:generate-proxies
454
455 Multiple Metadata Sources
456 -------------------------
457
458 When using different components using Doctrine 2 you may end up
459 with them using two different metadata drivers, for example XML and
460 YAML. You can use the DriverChain Metadata implementations to
461 aggregate these drivers based on namespaces:
462
4698346 @beberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
463 .. code-block:: php
1bfeaf3 @beberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
464
465 <?php
466 $chain = new DriverChain();
467 $chain->addDriver($xmlDriver, 'Doctrine\Tests\Models\Company');
468 $chain->addDriver($yamlDriver, 'Doctrine\Tests\ORM\Mapping');
469
470 Based on the namespace of the entity the loading of entities is
471 delegated to the appropriate driver. The chain semantics come from
472 the fact that the driver loops through all namespaces and matches
473 the entity class name against the namespace using a
474 ``strpos() === 0`` call. This means you need to order the drivers
475 correctly if sub-namespaces use different metadata driver
476 implementations.
477
478
Something went wrong with that request. Please try again.