Skip to content

Commit 6912795

Browse files
beberleifabpot
beberlei
authored and
fabpot
committed
Update Doctrine ORM Docs with new mapping configuration details.
1 parent e25b7fc commit 6912795

File tree

2 files changed

+154
-30
lines changed

2 files changed

+154
-30
lines changed

‎guides/doctrine/orm/configuration.rst

Lines changed: 113 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,109 @@
55
Configuration
66
=============
77

8+
In the overview we already described the only necessary configuration option "mappings"
9+
to get the Doctrine ORM running with Symfony 2. All the other configuration options are
10+
used with reasonable default values.
11+
12+
This following configuration example shows all the configuration defaults that the ORM resolves to:
13+
14+
.. code-block:: yaml
15+
16+
doctrine.orm:
17+
mappings:
18+
HelloBundle: ~
19+
auto_generate_proxy_classes: true
20+
proxy_namespace: Proxies
21+
proxy_dir: %kernel.cache_dir%/doctrine/orm/Proxies
22+
default_entity_manager: default
23+
default_connection: default
24+
metadata_cache_driver: array
25+
query_cache_driver: array
26+
result_cache_driver: array
27+
28+
There are lots of other configuration options that you can use to overwrite certain classes, but those
29+
are for very advanced use-cases only. You should look at the "orm.xml" file in the DoctrineBundle to
30+
get an overview of all the supported options.
31+
32+
For the caching drivers you can specifiy the values "array", "apc", "memcache" or "xcache".
33+
34+
The following example shows an overview of the caching configurations:
35+
36+
.. code-block:: yaml
37+
38+
doctrine.orm:
39+
mappings:
40+
HelloBundle: ~
41+
metadata_cache_driver: apc
42+
query_cache_driver: xcache
43+
result_cache_driver:
44+
type: memcache
45+
host: localhost
46+
port: 11211
47+
instance_class: Memcache
48+
49+
Mapping Configuration
50+
~~~~~~~~~~~~~~~~~~~~~
51+
52+
Explicit definition of all the mapped entities is the only necessary configuration for the ORM and there
53+
are several configuration options that you can control. The following configuration options exist
54+
for a mapping:
55+
56+
- ``type`` One of "annotations", "xml", "yml", "php" or "static-php". This specifies which type
57+
of metadata type your mapping uses.
58+
- ``dir`` Path to the mapping or entity files (depending on the driver). If this path is relative
59+
it is assumed to be relative to the bundle root. This only works if the name of your mapping
60+
is a bundle name. If you want to use this option to specifiy absolute paths you should prefix
61+
the path with the kernel parameters that exist in the DIC (for example %kernel.dir%).
62+
- ``prefix`` A common namespace prefix that all entities of this mapping share. This prefix
63+
should never conflict with prefixes of other defined mappings otherwise some of your entities cannot be found
64+
by Doctrine. This option defaults to the bundle namespace + `Entities`, for example for an
65+
application bundle called "Hello" prefix would be "Application\Hello\Entities".
66+
- ``alias`` Doctrine offers a way to alias entity namespaces to simpler, shorter names to be used
67+
in DQL queries or for Repository access.
68+
- ``is_bundle`` This option is a derived value from ``dir`` and by default is set to true if dir is relative
69+
proved by a ``file_exists()`` check that returns false. It is false if the existance check returns true.
70+
In this case an absolute path was specified and the metadata files are most likely in a directory outside of
71+
a bundle.
72+
73+
To avoid having to configure lots of information for your mappings you should follow these conventions:
74+
75+
1. Put all your entities in a directory Entities/ inside your bundle. For example "Application/Hello/Entities/".
76+
2. If you are using xml, yml or php mapping put all your configuration files into the
77+
"Resources/config/doctrine/metadata/doctrine/orm/" directory sufficed with dcm.xml, dcm.yml or dcm.php
78+
respectively.
79+
3. Annotations is assumed if an "Entities/" but no "Resources/config/doctrine/metadata/doctrine/orm/"
80+
directory is found.
81+
82+
The following configuration shows a bunch of mapping examples:
83+
84+
.. code-block:: yaml
85+
86+
doctrine.orm:
87+
mappings:
88+
MyBundle1: ~
89+
MyBundle2: yml
90+
MyBundle3: { type: annotation, dir: Entities/ }
91+
MyBundle4: { type: xml, dir: Resources/config/doctrine/mapping }
92+
MyBundle5:
93+
type: yml
94+
dir: my-bundle-mappings-dir
95+
alias: BundleAlias
96+
doctrine_extensions:
97+
type: xml
98+
dir: %kernel.dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Entities
99+
prefix: DoctrineExtensions\Entities\
100+
alias: DExt
101+
102+
Multiple Entity Managers
103+
~~~~~~~~~~~~~~~~~~~~~~~~
104+
105+
You can use multiple EntityManagers in a Symfony application. This is necessary
106+
if you are using different databases or even vendors with entirely different sets
107+
of entities.
108+
109+
The following configuration code shows how to define two EntityManagers:
110+
8111
.. code-block:: yaml
9112
10113
doctrine.orm:
@@ -17,37 +120,21 @@ Configuration
17120
connection: customer
18121
19122
Just like the DBAL, if you have configured multiple ``EntityManager`` instances
20-
and want to get a specific one you can use the ``getEntityManager()`` method by
21-
just passing it an argument that is the ``EntityManager`` name you want::
123+
and want to get a specific one you can use the full service name to retrieve
124+
it from the Symfony Dependency Injection Container:
22125

23126
class UserController extends Controller
24127
{
25128
public function indexAction()
26129
{
27-
$em = $this->get('doctrine.orm.customer_entity_manager');
28-
}
29-
}
30-
31-
Now the scenario arrises where you want to change your mapping information and
32-
update your development database schema without blowing away everything and
33-
losing your existing data. So first lets just add a new property to our ``User``
34-
entity::
35-
36-
namespace Application\HelloBundle\Entities;
37-
38-
/** @orm:Entity */
39-
class User
40-
{
41-
/** @orm:Column(type="string") */
42-
protected $new;
130+
$em = $this->get('doctrine.orm.entity_manager');
131+
$defaultEm = $this->get('doctrine.orm.default_entity_manager');
132+
$customerEm = $this->get('doctrine.orm.customer_entity_manager');
43133

44-
// ...
134+
// $em === $defaultEm => true
135+
// $defaultEm === $customerEm => false
136+
}
45137
}
46138

47-
Once you've done that, to get your database schema updated with the new column
48-
you just need to run the following command:
49-
50-
$ php app/console doctrine:schema:update
51-
52-
Now your database will be updated and the new column added to the database
53-
table.
139+
The service "doctrine.orm.entity_manager" is an alias for the default entity manager
140+
defined in the "default_entity_manager" configuration option.

‎guides/doctrine/orm/overview.rst

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,25 +14,34 @@ persistence for PHP objects.
1414
official `documentation`_ website.
1515

1616
To get started, enable and configure the :doc:`Doctrine DBAL
17-
</guides/doctrine/dbal/overview>`, then enable the ORM:
17+
</guides/doctrine/dbal/overview>`, then enable the ORM. The minimal
18+
necessary configuration is to specify the bundle name which contains your entities.
1819

1920
.. configuration-block::
2021

2122
.. code-block:: yaml
2223
2324
# app/config/config.yml
24-
doctrine.orm: ~
25+
doctrine.orm:
26+
mappings:
27+
HelloBundle: ~
2528
2629
.. code-block:: xml
2730
2831
<!-- xmlns:doctrine="http://www.symfony-project.org/schema/dic/doctrine" -->
2932
<!-- xsi:schemaLocation="http://www.symfony-project.org/schema/dic/doctrine http://www.symfony-project.org/schema/dic/doctrine/doctrine-1.0.xsd"> -->
3033
31-
<doctrine:orm />
34+
<doctrine:orm>
35+
<mappings>
36+
<mapping name="HelloBundle" />
37+
</mappings>
38+
</doctrine>
3239
3340
.. code-block:: php
3441
35-
$container->loadFromExtension('doctrine', 'orm');
42+
$container->loadFromExtension('doctrine', 'orm', array(
43+
"mappings" => array("HelloBundle" => array()),
44+
));
3645
3746
As Doctrine provides transparent persistence for PHP objects, it works with
3847
any PHP class::
@@ -145,6 +154,9 @@ the following commands:
145154
146155
Eventually, use your entity and manage its persistent state with Doctrine::
147156

157+
// Application/HelloBundle/Controller/UserController.php
158+
namespace Application\HelloBundle\Controller;
159+
148160
use Application\HelloBundle\Entity\User;
149161

150162
class UserController extends Controller
@@ -183,5 +195,30 @@ Eventually, use your entity and manage its persistent state with Doctrine::
183195
}
184196
}
185197

198+
Now the scenario arrises where you want to change your mapping information and
199+
update your development database schema without blowing away everything and
200+
losing your existing data. So first lets just add a new property to our ``User``
201+
entity::
202+
203+
namespace Application\HelloBundle\Entities;
204+
205+
/** @orm:Entity */
206+
class User
207+
{
208+
/** @orm:Column(type="string") */
209+
protected $new;
210+
211+
// ...
212+
}
213+
214+
Once you've done that, to get your database schema updated with the new column
215+
you just need to run the following command:
216+
217+
$ php app/console doctrine:schema:update
218+
219+
Now your database will be updated and the new column added to the database
220+
table.
221+
222+
186223
.. _documentation: http://www.doctrine-project.org/projects/orm/2.0/docs/en
187224
.. _Doctrine: http://www.doctrine-project.org

0 commit comments

Comments
 (0)