custom mapping in doctrine.rst

Author: timglabisch

reference/configuration/doctrine.rst

@@ -499,4 +499,137 @@ 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
+--------------
+
+It's possible to not rely on the auto mapping and set all the configuration
+on your own.
+
+For example, you can overwrite the configuration directory for a given bundle.
+Keep in mind that the bundle you want to overwrite has to exist.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+    
+        doctrine:
+            # ...
+            orm:
+                # ...
+                auto_mapping: true
+                mappings:
+                    # ...
+                    AppBundle:
+                        dir: Resources/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="Resources/config/doctrine" />
+                </doctrine:orm>
+            </doctrine:config>
+        </container>
+        
+    .. code-block:: php
+    
+        $container->loadFromExtension('doctrine', array(
+            'orm' => array(
+                'auto_mapping' => true,
+                'mappings' => array(
+                    'AppBundle' => array('dir' => 'Resources/config/doctrine'),
+                ),
+            ),
+        ));
+
+
+You can also create new mappings. For example outside of the Symfony folder.
+
+.. 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 MetadataDriver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the ``type`` on the bundle configuration isn't set,
+the DoctrineBundle will try to detect the correct metadata driver for
+the bundle. The DoctrineBundle will look for files following the filename pattern 
+``[BundleDirectory]/[ResourceConfigurationDirectory]/*.orm.[Extension]``.
+The ``ResourceConfigurationDirectory``, by default, points to
+``Resources/config/doctrine``.
+
+The bundle looks for (in this order) XML, YAML and PHP files.
+Every bundle can by default just register one ``MetadataDriver``.
+
+If it wasn't possible to determine a ``MetadataDriver``, it will check if
+there is an ``Entity`` folder in the bundle's root directory.
+If the folder does not exist, Doctrine will fall back to using an annotation driver.
+
+The Configuration Directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default configuration value depends on the used driver.
+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 you set the ``dir`` and the ``is_bundle`` bundle configuration to ``true``,
+it will be prefixed with the path of the current bundle and becomes
+the configuration directory.
+
 .. _`DQL User Defined Functions`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html