[WCM] document the doctrine compiler pass

cookbook/bundles/best_practices.rst

@@ -134,6 +134,12 @@ The following classes and files have specific emplacements:
 | Unit and Functional Tests    | ``Tests/``                  |
 +------------------------------+-----------------------------+
 
+.. note::
+
+    When building a reusable bundle, model classes should be placed in the
+    ``Model`` namespace. See doc:`../doctrine/mapping_model_classes` for
+    how to handle the mapping with a compiler pass.
+
 Classes
 -------
 

cookbook/doctrine/index.rst

@@ -12,4 +12,5 @@ Doctrine
     multiple_entity_managers
     custom_dql_functions
     resolve_target_entity
+    mapping_model_classes
     registration_form

cookbook/doctrine/mapping_model_classes.rst

@@ -0,0 +1,40 @@
+.. index::
+   single: Doctrine; Mapping Model classes
+
+How to provide model classes for several Doctrine implementations
+=================================================================
+
+When building a bundle that could be used not only with Doctrine ORM but
+also the CouchDB ODM, MongoDB ODM or PHPCR ODM, you should still only
+write one model class. The Doctrine bundles provide a compiler pass to
+register the mappings for your model classes.
+
+.. note::
+
+    For non-reusable bundles, the easiest is to put your model classes in
+    the default locations. ``Entity`` for Doctrine ORM, ``Document`` for one
+    of the ODMs. For reusable bundles, rather than duplicate model classes
+    just to get the auto mapping, use the compiler pass.
+
+
+In your bundle class, write the following code to register the compiler pass::
+
+    class FOSUserBundle extends Bundle
+    {
+        public function build(ContainerBuilder $container)
+        {
+            parent::build($container);
+            $container->addCompilerPass(new ValidationPass());
+
+            if (class_exists('Doctrine\Bundle\DoctrineBundle\DependencyInjection\Compiler\DoctrineOrmMappingsPass')) {
+                $mappings = array(
+                    realpath(__DIR__.'/Resources/config/doctrine/model') => 'FOS\UserBundle\Model',
+                );
+                $container->addCompilerPass(DoctrineOrmMappingsPass::createXmlMappingDriver($mappings, 'fos_user.backend_type_orm'));
+            }
+
+            // TODO: couch, mongo
+        }
+    }
+
+The compiler pass provides factory methods for all drivers: Annotations, XML, Yaml, PHP and StaticPHP.

cookbook/map.rst.inc

@@ -58,6 +58,7 @@
   * :doc:`/cookbook/doctrine/multiple_entity_managers`
   * :doc:`/cookbook/doctrine/custom_dql_functions`
   * :doc:`/cookbook/doctrine/resolve_target_entity`
+  * :doc:`/cookbook/doctrine/mapping_model_classes`
   * :doc:`/cookbook/doctrine/registration_form`
 
 * :doc:`/cookbook/email/index`