feature #4700 add informations how to create a custom doctrine mapping (timglabisch)

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4700).

Discussion
----------

add informations how to create a custom doctrine mapping

i tryed to explain a bit how doctrine tries to find the correct mapping, the driver and how you can configure your own mapping.

Commits
-------

8a98fc1 Update doctrine.rst
bec3c98 Doctrine Custom Mapping

Author: weaverryan

reference/configuration/doctrine.rst

@@ -521,4 +521,151 @@ can be placed directly under ``doctrine.orm`` config level.
 This shortened version is commonly used in other documentation sections.
 Keep in mind that you can't use both syntaxes at the same time.
 
+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. YAML, XML)
+in the ``Resources/config/doctrine`` directory.
+
+If you store metadata somewhere else in your bundle, you can define your own mappings,
+where you tell Doctrine exactly *where* to look, along with some other configurations.
+
+If you're using the ``auto_mapping`` configuration, you just need to overwrite the
+configurations you want. In this case it's important that the key of the mapping 
+configurations corresponds to the name of the bundle.
+
+For example, suppose you decide to store your ``XML`` configuration for ``AppBundle`` entities
+in the ``@AppBundle/SomeResources/config/doctrine`` directory instead:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+    
+        doctrine:
+            # ...
+            orm:
+                # ...
+                auto_mapping: true
+                mappings:
+                    # ...
+                    AppBundle:
+                        type: xml
+                        dir: SomeResources/config/doctrine
+                        
+    .. code-block:: xml
+    
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
+        
+            <doctrine:config>
+                <doctrine:orm auto-mapping="true">
+                    <mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml" />
+                </doctrine:orm>
+            </doctrine:config>
+        </container>
+        
+    .. code-block:: php
+    
+        $container->loadFromExtension('doctrine', array(
+            'orm' => array(
+                'auto_mapping' => true,
+                'mappings' => array(
+                    'AppBundle' => array('dir' => 'SomeResources/config/doctrine', 'type' => 'xml'),
+                ),
+            ),
+        ));
+
+Mapping Entities Outside of a Bundle
+------------------------------------
+
+You can also create new mappings, for example outside of the Symfony folder.
+
+For example, the following looks for entity classes in the ``App\Entity`` namespace in the
+``src/Entity`` directory and gives them an ``App`` alias (so you can say things like ``App:Post``):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+    
+        doctrine:
+                # ...
+                orm:
+                    # ...
+                    mappings:
+                        # ...
+                        SomeEntityNamespace:
+                            type: annotation
+                            dir: %kernel.root_dir%/../src/Entity
+                            is_bundle: false
+                            prefix: App\Entity
+                            alias: App
+                            
+    .. code-block:: xml
+    
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine">
+        
+            <doctrine:config>
+                <doctrine:orm>
+                    <mapping name="SomeEntityNamespace" 
+                        type="annotation"
+                        dir="%kernel.root_dir%/../src/Entity"
+                        is-bundle="false"
+                        prefix="App\Entity"
+                        alias="App"
+                    />
+                </doctrine:orm>
+            </doctrine:config>
+        </container>
+        
+    .. code-block:: php
+            
+        $container->loadFromExtension('doctrine', array(
+            'orm' => array(
+                'auto_mapping' => true,
+                'mappings' => array(
+                    'SomeEntityNamespace' => array(
+                        'type'      => 'annotation',
+                        'dir'       => '%kernel.root_dir%/../src/Entity',
+                        'is_bundle' => false,
+                        'prefix'    => 'App\Entity',
+                        'alias'     => 'App',
+                    ),
+                ),
+            ),
+        ));
+
+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.
+
+DoctrineBundle will look for files matching ``*.orm.[FORMAT]`` (e.g. ``Post.orm.yml``)
+in the configured ``dir`` of your mapping (if you're mapping a bundle, then ``dir`` is
+relative to the bundle's directory).
+
+The bundle looks for (in this order) XML, YAML and PHP files.
+Using the ``auto_mapping`` feature, every bundle can have only one configuration format.
+The bundle will stop as soon as it locates one.
+
+If it wasn't possible to determine a configuration format for a bundle,
+the DoctrineBundle will check if there is an ``Entity`` folder in the bundle's 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, staticphp) it will
+be ``[Bundle]/Entity``. For drivers that are using configuration
+files (XML, YAML, ...) it will be ``[Bundle]/Resources/config/doctrine``.
+
+If the ``dir`` configuration is set and the ``is_bundle`` configuration is ``true``,
+the DoctrineBundle will prefix the ``dir`` configuration with the path of the bundle.
+
 .. _`DQL User Defined Functions`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html