[DoctrineMongoDBBundle] Updating documentation for recent changes.

symfony · adell · Jun 25, 2010 · Jul 20, 2010 · Jul 26, 2010 · Jul 23, 2010
commit 5bb596a8fc83fbd3baad7ab5b2c68fd18b33089f
diff --git a/guides/en/Doctrine/Configuration.markdown b/guides/en/Doctrine/Configuration.markdown
@@ -4,8 +4,6 @@ Doctrine Configuration
 DBAL Configuration
 ------------------
 
-
-
     [yml]
     # config/config.yml
     doctrine.dbal:
@@ -61,14 +59,14 @@ but you must pass it an argument with the name of the connection you want to get
 ORM Configuration
 -----------------
 
-doctrine.orm:
-  default_entity_manager:   default
-  cache_driver:             apc           # array, apc, memcache, xcache
-  entity_managers:
-    default:
-      connection:           default
-    customer:
-      connection:           customer
+    doctrine.orm:
+      default_entity_manager:   default
+      cache_driver:             apc           # array, apc, memcache, xcache
+      entity_managers:
+        default:
+          connection:           default
+        customer:
+          connection:           customer
 
 Just like the DBAL, if you have configured multiple `EntityManager` instances and want to
 get a specific one you can use the `getEntityManager()` method by just passing it an argument
@@ -107,11 +105,6 @@ you just need to run the following command:
 Now your database will be updated and the new column added to the database
 table.
 
-MongoDB Configuration
----------------------
-
-
-
 Console Commands
 ----------------
 
@@ -151,4 +144,4 @@ or options:
       :drop                        Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
       :update                      Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.
 
-    ...
+    ...
diff --git a/guides/en/Doctrine/MongoDB.markdown b/guides/en/Doctrine/MongoDB.markdown
@@ -2,83 +2,202 @@ MongoDB
 =======
 
 The [MongoDB][1] Object Document Mapper is much like the Doctrine2 ORM in the
-way it works and architecture. The plain PHP5 objects are persisted
-transparently.
+way it works and architecture. You only deal with plain PHP objects and they are persisted
+transparently without imposing on your domain model.
 
 >**TIP**
 >You can read more about the Doctrine MongoDB Object Document Mapper on the
 >projects [documentation][2].
 
-To get started working with Doctrine and MongoDB you just need to configure it:
+## Configuration
+
+To get started working with Doctrine and the MongoDB Object Document Mapper you just need
+to enable it:
+
+    # config/config.yml
+    doctrine_odm.mongodb: ~
+
+The above YAML is the most simple example and uses all of the default values provided, if
+you need to customize more you can specify the complete configuration:
+
+    # config/config.yml
+    doctrine_odm.mongodb:
+      server: mongodb://localhost:27017
+      options:
+        connect: true
+      metadata_cache_driver: array # array, apc, xcache, memcache
+
+If you wish to use memcache to cache your metadata and you need to configure the `Memcache` instance you can do the following:
 
-    [yml]
     # config/config.yml
     doctrine_odm.mongodb:
-        default_document_manager: default
-        cache_driver:             array
-        document_managers:
-            default:
-                connection: mongodb
-        connections:
-            mongodb:
-                server:           localhost
-                default_database: jwage
-
-Working with documents and MongoDB is very similar to how you work with
-entities in the ORM. You are only dealing with plain PHP objects that are
-mapped to MongoDB:
-
-    [php]
-    namespace Application\HelloBundle\Documents;
-
-    /**
-     * @Document
-     */
+      server: mongodb://localhost:27017
+      options:
+        connect: true
+      metadata_cache_driver:
+        type: memcache
+        class: Doctrine\Common\Cache\MemcacheCache
+        host: localhost
+        port: 11211
+        instance_class: Memcache
+
+### Multiple Connections
+
+If you need multiple connections and document managers you can use the following syntax:
+
+    doctrine_odm.mongodb:
+      default_connection: conn2
+      default_document_manager: dm2
+      metadata_cache_driver: apc
+      connections:
+        conn1:
+          server: mongodb://localhost:27017
+          options:
+            connect: true
+        conn2:
+          server: mongodb://localhost:27017
+          options:
+            connect: true
+      document_managers:
+        dm1:
+          connection: conn1
+          metadata_cache_driver: xcache
+        dm2:
+          connection: conn2
+
+Now you can retrieve the configured services connection services:
+
+    $conn1 = $container->getService('doctrine.odm.mongodb.conn1_connection');
+    $conn2 = $container->getService('doctrine.odm.mongodb.conn2_connection');
+
+And you can also retrieve the configured document manager services which utilize the above
+connection services:
+
+    $dm1 = $container->getService('doctrine.odm.mongodb.dm1_connection');
+    $dm2 = $container->getService('doctrine.odm.mongodb.dm1_connection');
+
+### XML
+
+You can specify the same configuration via XML if you prefer that. Here are the same
+examples from above in XML.
+
+Simple Single Connection:
+
+    <?xml version="1.0" ?>
+
+    <container xmlns="http://www.symfony-project.org/schema/dic/services"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns:doctrine="http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb"
+        xsi:schemaLocation="http://www.symfony-project.org/schema/dic/services http://www.symfony-project.org/schema/dic/services/services-1.0.xsd
+                            http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb/mongodb-1.0.xsd">
+
+        <doctrine:mongodb server="mongodb://localhost:27017">
+            <metadata_cache_driver type="memcache">
+                <class>Doctrine\Common\Cache\MemcacheCache</class>
+                <host>localhost</host>
+                <port>11211</port>
+                <instance_class>Memcache</instance_class>
+            </metadata_cache_driver>
+            <options>
+                <connect>true</connect>
+            </options>
+        </doctrine:mongodb>
+    </container>
+
+Multiple Connections:
+
+    <?xml version="1.0" ?>
+
+    <container xmlns="http://www.symfony-project.org/schema/dic/services"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns:doctrine="http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb"
+        xsi:schemaLocation="http://www.symfony-project.org/schema/dic/services http://www.symfony-project.org/schema/dic/services/services-1.0.xsd
+                            http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb http://www.symfony-project.org/schema/dic/doctrine/odm/mongodb/mongodb-1.0.xsd">
+
+        <doctrine:mongodb
+                metadata_cache_driver="apc"
+                default_document_manager="dm2"
+                default_connection="dm2"
+                proxy_namespace="Proxies"
+                auto_generate_proxy_classes="true"
+            >
+            <doctrine:connections>
+                <doctrine:connection id="conn1" server="mongodb://localhost:27017">
+                    <options>
+                        <connect>true</connect>
+                    </options>
+                </doctrine:connection>
+                <doctrine:connection id="conn2" server="mongodb://localhost:27017">
+                    <options>
+                        <connect>true</connect>
+                    </options>
+                </doctrine:connection>
+            </doctrine:connections>
+            <doctrine:document_managers>
+                <doctrine:document_manager id="dm1" server="mongodb://localhost:27017" metadata_cache_driver="xcache" connection="conn1" />
+                <doctrine:document_manager id="dm2" server="mongodb://localhost:27017" connection="conn2" />
+            </doctrine:document_managers>
+        </doctrine:mongodb>
+    </container>
+
+## Writing Document Classes
+
+You can start writing document classes just how you normally would write some PHP classes.
+The only difference is that you must map the classes to the MongoDB ODM. You can provide
+the mapping information via xml, yaml or annotations. In this example, for simplicity and
+ease of reading we will use annotations.
+
+First, lets write a simple User class:
+
+    // src/Application/HelloBundle/Document/User.php
+
+    namespace Application\HelloBundle\Document;
+
     class User
     {
-        /**
-         * @Id
-         */
         protected $id;
-
-        /**
-         * @String
-         */
         protected $name;
 
-        /**
-         * Get id
-         *
-         * @return integer $id
-         */
         public function getId()
         {
             return $this->id;
         }
 
-        /**
-         * Set name
-         *
-         * @param string $name
-         */
         public function setName($name)
         {
             $this->name = $name;
         }
 
-        /**
-         * Get name
-         *
-         * @return string $name
-         */
         public function getName()
         {
             return $this->name;
         }
     }
 
-Now that you have a document created and mapped properly you can begin
-managing its persistent state with Doctrine:
+This class can be used independent from any persistence layer as it is a regular PHP
+class and does not have any dependencies. Now we need to annotate the class so Doctrine
+can read the annotated mapping information from the doc blocks:
+
+    // ...
+
+    /** @Document(collection="users") */
+    class User
+    {
+        /** @Id */
+        protected $id;
+
+        /** @String */
+        protected $name;
+
+        // ...
+    }
+
+## Using Documents
+
+Now that you have a PHP class that has been mapped properly you can begin working with
+instances of that document persisting to and retrieving from MongoDB.
+
+From your controllers you can access the `DocumentManager` instances from the container:
 
     class UserController extends Controller
     {
@@ -93,29 +212,20 @@ managing its persistent state with Doctrine:
 
             // ...
         }
+    }
 
-        public function editAction($id)
-        {
-            $dm = $this->container->getService('doctrine.odm.mongodb.document_manager');
-            $user = $dm->createQuery('HelloBundle:User')
-                ->where('id', $id)
-                ->getSingleResult();
-            $user->setBody('new body');
-            $dm->flush();
-        }
+Later you can retrieve the persisted document by its id:
 
-        public function deleteAction($id)
+    class UserController extends Controller
+    {
+        public function editAction($id)
         {
             $dm = $this->container->getService('doctrine.odm.mongodb.document_manager');
-            $user = $dm->createQuery('HelloBundle:User')
-                ->where('id', $id)
-                ->getSingleResult();
-            $dm->remove($user);
-            $dm->flush();
+            $user = $dm->find('HelloBundle:User', $id);
 
-          // ...
+            // ...
         }
     }
 
 [1]: http://www.mongodb.org/
-[2]: http://www.doctrine-project.org/projects/mongodb_odm/1.0/docs/en
+[2]: http://www.doctrine-project.org/projects/mongodb_odm/1.0/docs/en