Merge branch '2.8' into 3.3

* 2.8:
  Reorder DoctrineBundle configuration sections

Author: weaverryan

reference/configuration/doctrine.rst

@@ -270,102 +270,6 @@ Full Default Configuration
             </doctrine:config>
         </container>
 
-Configuration Overview
-----------------------
-
-This following configuration example shows all the configuration defaults
-that the ORM resolves to:
-
-.. code-block:: yaml
-
-    doctrine:
-        orm:
-            auto_mapping: true
-            # the standard distribution overrides this to be true in debug, false otherwise
-            auto_generate_proxy_classes: false
-            proxy_namespace: Proxies
-            proxy_dir: '%kernel.cache_dir%/doctrine/orm/Proxies'
-            default_entity_manager: default
-            metadata_cache_driver: array
-            query_cache_driver: array
-            result_cache_driver: array
-
-There are lots of other configuration options that you can use to overwrite
-certain classes, but those are for very advanced use-cases only.
-
-Caching Drivers
-~~~~~~~~~~~~~~~
-
-The built-in types of caching drivers are: ``array``, ``apc``, ``apcu``,
-``memcache``, ``memcached``, ``redis``, ``wincache``, ``zenddata`` and ``xcache``.
-There is a special type called ``service`` which lets you define the ID of your
-own caching service.
-
-The following example shows an overview of the caching configurations:
-
-.. code-block:: yaml
-
-    doctrine:
-        orm:
-            auto_mapping: true
-            # each caching driver type defines its own config options
-            metadata_cache_driver: apc
-            result_cache_driver:
-                type: memcache
-                host: localhost
-                port: 11211
-                instance_class: Memcache
-            # the 'service' type requires to define the 'id' option too
-            query_cache_driver:
-                type: service
-                id: my_doctrine_common_cache_service
-
-Mapping Configuration
-~~~~~~~~~~~~~~~~~~~~~
-
-Explicit definition of all the mapped entities is the only necessary
-configuration for the ORM and there are several configuration options that
-you can control. The following configuration options exist for a mapping:
-
-type
-....
-
-One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. This
-specifies which type of metadata type your mapping uses.
-
-dir
-...
-
-Path to the mapping or entity files (depending on the driver). If this path
-is relative it is assumed to be relative to the bundle root. This only works
-if the name of your mapping is a bundle name. If you want to use this option
-to specify absolute paths you should prefix the path with the kernel parameters
-that exist in the DIC (for example ``%kernel.project_dir%``).
-
-prefix
-......
-
-A common namespace prefix that all entities of this mapping share. This
-prefix should never conflict with prefixes of other defined mappings otherwise
-some of your entities cannot be found by Doctrine. This option defaults
-to the bundle namespace + ``Entity``, for example for an application bundle
-called AcmeHelloBundle prefix would be ``Acme\HelloBundle\Entity``.
-
-alias
-.....
-
-Doctrine offers a way to alias entity namespaces to simpler, shorter names
-to be used in DQL queries or for Repository access. When using a bundle
-the alias defaults to the bundle name.
-
-is_bundle
-.........
-
-This option is a derived value from ``dir`` and by default is set to ``true``
-if dir is relative proved by a ``file_exists()`` check that returns ``false``.
-It is ``false`` if the existence check returns ``true``. In this case an
-absolute path was specified and the metadata files are most likely in a
-directory outside of a bundle.
 
 .. index::
     single: Configuration; Doctrine DBAL
@@ -492,41 +396,111 @@ service where ``[name]`` is the name of the connection.
 
 .. _DBAL documentation: http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html
 
-Shortened Configuration Syntax
-------------------------------
+Doctrine ORM Configuration
+--------------------------
 
-When you are only using one entity manager, all config options available
-can be placed directly under ``doctrine.orm`` config level.
+This following configuration example shows all the configuration defaults
+that the ORM resolves to:
 
 .. code-block:: yaml
 
     doctrine:
         orm:
-            # ...
-            query_cache_driver:
-               # ...
-            metadata_cache_driver:
-                # ...
+            auto_mapping: true
+            # the standard distribution overrides this to be true in debug, false otherwise
+            auto_generate_proxy_classes: false
+            proxy_namespace: Proxies
+            proxy_dir: '%kernel.cache_dir%/doctrine/orm/Proxies'
+            default_entity_manager: default
+            metadata_cache_driver: array
+            query_cache_driver: array
+            result_cache_driver: array
+
+There are lots of other configuration options that you can use to overwrite
+certain classes, but those are for very advanced use-cases only.
+
+Caching Drivers
+~~~~~~~~~~~~~~~
+
+The built-in types of caching drivers are: ``array``, ``apc``, ``apcu``,
+``memcache``, ``memcached``, ``redis``, ``wincache``, ``zenddata`` and ``xcache``.
+There is a special type called ``service`` which lets you define the ID of your
+own caching service.
+
+The following example shows an overview of the caching configurations:
+
+.. code-block:: yaml
+
+    doctrine:
+        orm:
+            auto_mapping: true
+            # each caching driver type defines its own config options
+            metadata_cache_driver: apc
             result_cache_driver:
-                # ...
-            connection: ~
-            class_metadata_factory_name:  Doctrine\ORM\Mapping\ClassMetadataFactory
-            default_repository_class:  Doctrine\ORM\EntityRepository
-            auto_mapping: false
-            hydrators:
-                # ...
-            mappings:
-                # ...
-            dql:
-                # ...
-            filters:
-                # ...
+                type: memcache
+                host: localhost
+                port: 11211
+                instance_class: Memcache
+            # the 'service' type requires to define the 'id' option too
+            query_cache_driver:
+                type: service
+                id: my_doctrine_common_cache_service
+
+Mapping Configuration
+~~~~~~~~~~~~~~~~~~~~~
 
-This shortened version is commonly used in other documentation sections.
-Keep in mind that you can't use both syntaxes at the same time.
+Explicit definition of all the mapped entities is the only necessary
+configuration for the ORM and there are several configuration options that
+you can control. The following configuration options exist for a mapping:
+
+type
+....
+
+One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. This
+specifies which type of metadata type your mapping uses.
+
+dir
+...
+
+Path to the mapping or entity files (depending on the driver). If this path
+is relative it is assumed to be relative to the bundle root. This only works
+if the name of your mapping is a bundle name. If you want to use this option
+to specify absolute paths you should prefix the path with the kernel parameters
+that exist in the DIC (for example ``%kernel.project_dir%``).
+
+prefix
+......
+
+A common namespace prefix that all entities of this mapping share. This
+prefix should never conflict with prefixes of other defined mappings otherwise
+some of your entities cannot be found by Doctrine. This option defaults
+to the bundle namespace + ``Entity``, for example for an application bundle
+called AcmeHelloBundle prefix would be ``Acme\HelloBundle\Entity``.
+
+alias
+.....
+
+Doctrine offers a way to alias entity namespaces to simpler, shorter names
+to be used in DQL queries or for Repository access. When using a bundle
+the alias defaults to the bundle name.
+
+is_bundle
+.........
+
+This option is a derived value from ``dir`` and by default is set to ``true``
+if dir is relative proved by a ``file_exists()`` check that returns ``false``.
+It is ``false`` if the existence check returns ``true``. In this case an
+absolute path was specified and the metadata files are most likely in a
+directory outside of a bundle.
+
+.. index::
+    single: Configuration; Doctrine DBAL
+    single: Doctrine; DBAL configuration
+
+.. _`reference-dbal-configuration`:
 
 Custom Mapping Entities in a Bundle
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Doctrine's ``auto_mapping`` feature loads annotation configuration from
 the ``Entity/`` directory of each bundle *and* looks for other formats (e.g.
@@ -587,7 +561,7 @@ directory instead:
         ));
 
 Mapping Entities Outside of a Bundle
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also create new mappings, for example outside of the Symfony folder.
 
@@ -652,7 +626,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias
         ));
 
 Detecting a Mapping Configuration Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+........................................
 
 If the ``type`` on the bundle configuration isn't set, the DoctrineBundle
 will try to detect the correct mapping configuration format for the bundle.
@@ -671,7 +645,7 @@ root directory. If the folder exist, Doctrine will fall back to using an
 annotation driver.
 
 Default Value of Dir
-~~~~~~~~~~~~~~~~~~~~
+....................
 
 If ``dir`` is not specified, then its default value depends on which configuration
 driver is being used. For drivers that rely on the PHP files (annotation,