[symfony#2669] Proofreading and minor fixes for updates to mapping mode classes

weaverryan · weaverryan · commit e55f0f72a146 · 2013-06-30T14:22:01.000-05:00
1) Fixed missed second argument to the `createXmlMappingDriver` methods

2) Clarified the final note about the SymfonyFileLocator

3) Other minor changes
diff --git a/cookbook/doctrine/mapping_model_classes.rst b/cookbook/doctrine/mapping_model_classes.rst
@@ -17,7 +17,6 @@ register the mappings for your model classes.
     just to get the auto mapping, use the compiler pass.
 
 .. versionadded:: 2.3
-
     The base mapping compiler pass was added 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
@@ -30,7 +29,9 @@ register the mappings for your model classes.
     ``addRegisterMappingsPass``.
 
 
-In your bundle class, write the following code to register the compiler pass::
+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
+be adapted for your case::
 
     use Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass;
     use Doctrine\Bundle\MongoDBBundle\DependencyInjection\Compiler\DoctrineMongoDBMappingsPass;
@@ -54,6 +55,7 @@ In your bundle class, write the following code to register the compiler pass::
                 $container->addCompilerPass(
                     DoctrineOrmMappingsPass::createXmlMappingDriver(
                         $mappings,
+                        array('fos_user.model_manager_name'),
                         'fos_user.backend_type_orm'
                 ));
             }
@@ -63,6 +65,7 @@ In your bundle class, write the following code to register the compiler pass::
                 $container->addCompilerPass(
                     DoctrineMongoDBMappingsPass::createXmlMappingDriver(
                         $mappings,
+                        array('fos_user.model_manager_name'),
                         'fos_user.backend_type_mongodb'
                 ));
             }
@@ -72,6 +75,7 @@ In your bundle class, write the following code to register the compiler pass::
                 $container->addCompilerPass(
                     DoctrineCouchDBMappingsPass::createXmlMappingDriver(
                         $mappings,
+                        array('fos_user.model_manager_name'),
                         'fos_user.backend_type_couchdb'
                 ));
             }
@@ -81,6 +85,7 @@ In your bundle class, write the following code to register the compiler pass::
                 $container->addCompilerPass(
                     DoctrinePhpcrMappingsPass::createXmlMappingDriver(
                         $mappings,
+                        array('fos_user.model_manager_name'),
                         'fos_user.backend_type_phpcr'
                 ));
             }
@@ -94,12 +99,13 @@ 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 of absolute directory path to namespace;
+* 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. 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;
+  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``
+  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
   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
@@ -109,8 +115,14 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
 
     The factory method is using the ``SymfonyFileLocator`` of Doctrine, meaning
     it will only see XML and YML mapping files if they do not contain the
-    namespace. If you also need to map a base class, you can register a
-    compiler pass with the ``DefaultFileLocator`` like this::
+    full namespace as the filename. This is by design: the ``SymfonyFileLocator``
+    simplifies things by assuming the files are just the "short" version
+    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
+    ``DoctrineOrmMappingsPass`` and adapted to use the ``DefaultFileLocator``
+    instead of the ``SymfonyFileLocator``::
 
         private function buildMappingCompilerPass()
         {
@@ -126,7 +138,7 @@ Annotations, XML, Yaml, PHP and StaticPHP. The arguments are:
             );
         }
 
-    And place your mapping file into ``/Resources/config/doctrine-base`` with the
+    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
     the SymfonyFileLocator will get confused.
