feature #4069 document the namespace alias feature (dbu)

This PR was merged into the master branch.

Discussion
----------

document the namespace alias feature

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | [yes](symfony/symfony#10853)
| Applies to    | 2.6
| Fixed tickets | -

Commits
-------

d753d0e document the namespace alias feature

cookbook/doctrine/mapping_model_classes.rst

@@ -14,31 +14,31 @@ register the mappings for your model classes.
     For non-reusable bundles, the easiest option is to put your model classes
     in the default locations: ``Entity`` for the Doctrine ORM or ``Document``
     for one of the ODMs. For reusable bundles, rather than duplicate model classes
-    just to get the auto mapping, use the compiler pass.
+    just to get the auto-mapping, use the compiler pass.
 
 .. versionadded:: 2.3
     The base mapping compiler pass was introduced in Symfony 2.3. The Doctrine bundles
     support it from DoctrineBundle >= 1.2.1, MongoDBBundle >= 3.0.0,
-    PHPCRBundle >= 1.0.0-alpha2 and the (unversioned) CouchDBBundle supports the
+    PHPCRBundle >= 1.0.0 and the (unversioned) CouchDBBundle supports the
     compiler pass since the `CouchDB Mapping Compiler Pass pull request`_
     was merged.
 
-    If you want your bundle to support older versions of Symfony and
-    Doctrine, you can provide a copy of the compiler pass in your bundle.
-    See for example the `FOSUserBundle mapping configuration`_
-    ``addRegisterMappingsPass``.
-
+.. versionadded:: 2.6
+    Support for defining namespace aliases was introduced in Symfony 2.6.
+    It is safe to define the aliases with older versions of Symfony as
+    the aliases are the last argument to ``createXmlMappingDriver`` and
+    are ignored by PHP if that argument doesn't exist.
 
 In your bundle class, write the following code to register the compiler pass.
-This one is written for the FOSUserBundle, so parts of it will need to
+This one is written for the CmfRoutingBundle, so parts of it will need to
 be adapted for your case::
 
     use Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass;
     use Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass;
     use Doctrine\Bundle\CouchDBBundle\DependencyInjection\Compiler\DoctrineCouchDBMappingsPass;
     use Doctrine\Bundle\PHPCRBundle\DependencyInjection\Compiler\DoctrinePhpcrMappingsPass;
 
-    class FOSUserBundle extends Bundle
+    class CmfRoutingBundle extends Bundle
     {
         public function build(ContainerBuilder $container)
         {
@@ -47,16 +47,17 @@ be adapted for your case::
 
             $modelDir = realpath(__DIR__.'/Resources/config/doctrine/model');
             $mappings = array(
-                $modelDir => 'FOS\UserBundle\Model',
+                $modelDir => 'Symfony\Cmf\RoutingBundle\Model',
             );
 
             $ormCompilerClass = 'Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass';
             if (class_exists($ormCompilerClass)) {
                 $container->addCompilerPass(
                     DoctrineOrmMappingsPass::createXmlMappingDriver(
                         $mappings,
-                        array('fos_user.model_manager_name'),
-                        'fos_user.backend_type_orm'
+                        array('cmf_routing.model_manager_name'),
+                        'cmf_routing.backend_type_orm',
+                        array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
                 ));
             }
 
@@ -65,8 +66,9 @@ be adapted for your case::
                 $container->addCompilerPass(
                     DoctrineMongoDBMappingsPass::createXmlMappingDriver(
                         $mappings,
-                        array('fos_user.model_manager_name'),
-                        'fos_user.backend_type_mongodb'
+                        array('cmf_routing.model_manager_name'),
+                        'cmf_routing.backend_type_mongodb',
+                        array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
                 ));
             }
 
@@ -75,8 +77,9 @@ be adapted for your case::
                 $container->addCompilerPass(
                     DoctrineCouchDBMappingsPass::createXmlMappingDriver(
                         $mappings,
-                        array('fos_user.model_manager_name'),
-                        'fos_user.backend_type_couchdb'
+                        array('cmf_routing.model_manager_name'),
+                        'cmf_routing.backend_type_couchdb',
+                        array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
                 ));
             }
 
@@ -85,8 +88,9 @@ be adapted for your case::
                 $container->addCompilerPass(
                     DoctrinePhpcrMappingsPass::createXmlMappingDriver(
                         $mappings,
-                        array('fos_user.model_manager_name'),
-                        'fos_user.backend_type_phpcr'
+                        array('cmf_routing.model_manager_name'),
+                        'cmf_routing.backend_type_phpcr',
+                        array('CmfRoutingBundle' => 'Symfony\Cmf\RoutingBundle\Model')
                 ));
             }
         }
@@ -99,17 +103,20 @@ decide which to use.
 The compiler pass provides factory methods for all drivers provided by Doctrine:
 Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
 
-* a map/hash of absolute directory path to namespace;
-* an array of container parameters that your bundle uses to specify the name of
-  the Doctrine manager that it is using. In the above example, the FOSUserBundle
-  stores the manager name that's being used under the ``fos_user.model_manager_name``
+* A map/hash of absolute directory path to namespace;
+* An array of container parameters that your bundle uses to specify the name of
+  the Doctrine manager that it is using. In the example above, the CmfRoutingBundle
+  stores the manager name that's being used under the ``cmf_routing.model_manager_name``
   parameter. The compiler pass will append the parameter Doctrine is using
   to specify the name of the default manager. The first parameter found is
   used and the mappings are registered with that manager;
-* an optional container parameter name that will be used by the compiler
+* An optional container parameter name that will be used by the compiler
   pass to determine if this Doctrine type is used at all. This is relevant if
   your user has more than one type of Doctrine bundle installed, but your
-  bundle is only used with one type of Doctrine.
+  bundle is only used with one type of Doctrine;
+* A map/hash of aliases to namespace. This should be the same convention used
+  by Doctrine auto-mapping. In the example above, this allows the user to call
+  ``$om->getRepository('CmfRoutingBundle:Route')``.
 
 .. note::
 
@@ -120,7 +127,7 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
     of the class as their filename (e.g. ``BlogPost.orm.xml``)
 
     If you also need to map a base class, you can register a compiler pass
-    with the ``DefaultFileLocator`` like this. This code is simply taken from the
+    with the ``DefaultFileLocator`` like this. This code is taken from the
     ``DoctrineOrmMappingsPass`` and adapted to use the ``DefaultFileLocator``
     instead of the ``SymfonyFileLocator``::
 
@@ -138,6 +145,9 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
             );
         }
 
+    Note that you do not need to provide a namespace alias unless your users are
+    expected to ask Doctrine for the base classes.
+
     Now place your mapping file into ``/Resources/config/doctrine-base`` with the
     fully qualified class name, separated by ``.`` instead of ``\``, for example
     ``Other.Namespace.Model.Name.orm.xml``. You may not mix the two as otherwise
@@ -146,4 +156,3 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
     Adjust accordingly for the other Doctrine implementations.
 
 .. _`CouchDB Mapping Compiler Pass pull request`: https://github.com/doctrine/DoctrineCouchDBBundle/pull/27
-.. _`FOSUserBundle mapping configuration`: https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/FOSUserBundle.php