Skip to content

Commit eff58a0

Browse files
beberleibeberlei
committed
Merge remote branch 'symfony/master'
2 parents b0294b6 + b969c43 commit eff58a0

File tree

10 files changed

+497
-104
lines changed

10 files changed

+497
-104
lines changed

‎guides/doctrine/mongodb-odm/configuration.rst

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,65 @@ If you wish to use memcache to cache your metadata, you need to configure the
3333
port: 11211
3434
instance_class: Memcache
3535
36+
Mapping Configuration
37+
~~~~~~~~~~~~~~~~~~~~~
38+
39+
Explicit definition of all the mapped documents is the only necessary
40+
configuration for the ODM and there are several configuration options that you
41+
can control. The following configuration options exist for a mapping:
42+
43+
- ``type`` One of "annotations", "xml", "yml", "php" or "static-php". This
44+
specifies which type of metadata type your mapping uses.
45+
- ``dir`` Path to the mapping or entity files (depending on the driver). If
46+
this path is relative it is assumed to be relative to the bundle root. This
47+
only works if the name of your mapping is a bundle name. If you want to use
48+
this option to specifiy absolute paths you should prefix the path with the
49+
kernel parameters that exist in the DIC (for example %kernel.dir%).
50+
- ``prefix`` A common namespace prefix that all documents of this mapping
51+
share. This prefix should never conflict with prefixes of other defined
52+
mappings otherwise some of your documents cannot be found by Doctrine. This
53+
option defaults to the bundle namespace + `Documents`, for example for an
54+
application bundle called "Hello" prefix would be
55+
"Application\Hello\Documents".
56+
- ``alias`` Doctrine offers a way to alias document namespaces to simpler,
57+
shorter names to be used inqueries or for Repository access.
58+
- ``is_bundle`` This option is a derived value from ``dir`` and by default is
59+
set to true if dir is relative proved by a ``file_exists()`` check that
60+
returns false. It is false if the existance check returns true. In this case
61+
an absolute path was specified and the metadata files are most likely in a
62+
directory outside of a bundle.
63+
64+
To avoid having to configure lots of information for your mappings you should
65+
follow these conventions:
66+
67+
1. Put all your entities in a directory Documents/ inside your bundle. For
68+
example "Application/Hello/Documents/".
69+
2. If you are using xml, yml or php mapping put all your configuration files
70+
into the "Resources/config/doctrine/metadata/doctrine/mongodb/" directory
71+
sufficed with dcm.xml, dcm.yml or dcm.php respectively.
72+
3. Annotations is assumed if an "Documents/" but no
73+
"Resources/config/doctrine/metadata/doctrine/mongodb/" directory is found.
74+
75+
The following configuration shows a bunch of mapping examples:
76+
77+
.. code-block:: yaml
78+
79+
doctrine.mongodb:
80+
mappings:
81+
MyBundle1: ~
82+
MyBundle2: yml
83+
MyBundle3: { type: annotation, dir: Documents/ }
84+
MyBundle4: { type: xml, dir: Resources/config/doctrine/mapping }
85+
MyBundle5:
86+
type: yml
87+
dir: my-bundle-mappings-dir
88+
alias: BundleAlias
89+
doctrine_extensions:
90+
type: xml
91+
dir: %kernel.dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Documents
92+
prefix: DoctrineExtensions\Documents\
93+
alias: DExt
94+
3695
Multiple Connections
3796
~~~~~~~~~~~~~~~~~~~~
3897

@@ -76,8 +135,8 @@ connection services::
76135
XML
77136
~~~
78137

79-
You can specify the same configuration via XML if you prefer that. Here are the
80-
same examples from above in XML.
138+
You can specify the same configuration via XML if you prefer that. Here are
139+
the same examples from above in XML.
81140

82141
Simple Single Connection:
83142

‎guides/doctrine/mongodb-odm/overview.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,15 @@ persisted transparently without imposing on your domain model.
1414
projects `documentation`_.
1515

1616
To get started working with Doctrine and the MongoDB Object Document Mapper you
17-
just need to enable it:
17+
just need to enable it and specify the bundle that contains your mapped documents:
1818

1919
.. code-block:: yaml
2020
2121
# app/config/config.yml
2222
23-
doctrine_odm.mongodb: ~
23+
doctrine_odm.mongodb:
24+
mappings:
25+
HelloBundle: ~
2426
2527
Now you can start writing documents and mapping them with annotations, xml, or
2628
yaml. In this example we will use annotations::

‎guides/doctrine/orm/configuration.rst

Lines changed: 123 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,118 @@
55
Configuration
66
=============
77

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

23135
class UserController extends Controller
24136
{
25137
public function indexAction()
26138
{
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;
139+
$em = $this->get('doctrine.orm.entity_manager');
140+
$defaultEm = $this->get('doctrine.orm.default_entity_manager');
141+
$customerEm = $this->get('doctrine.orm.customer_entity_manager');
43142

44-
// ...
143+
// $em === $defaultEm => true
144+
// $defaultEm === $customerEm => false
145+
}
45146
}
46147

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.
148+
The service "doctrine.orm.entity_manager" is an alias for the default entity
149+
manager 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

‎guides/map.rst.inc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@
3535
* :doc:`Overview </guides/security/overview>` |
3636
* :doc:`/guides/security/users` |
3737
* :doc:`/guides/security/authentication` |
38-
* :doc:`/guides/security/authorization`
38+
* :doc:`/guides/security/authorization` |
39+
* :doc:`ACLs </guides/security/acl>` |
40+
* :doc:`Advanced ACLs </guides/security/acl_advanced>`
3941

4042
* **Cache**:
4143

0 commit comments

Comments
 (0)