Split documentation

Resources/doc/config.rst

@@ -1,5 +1,5 @@
-DoctrineMongoDBBundle Configuration
-===================================
+Configuration
+=============
 
 Sample Configuration
 --------------------
@@ -120,7 +120,7 @@ If you wish to use memcache to cache your metadata, you need to configure the
 
 
 Mapping Configuration
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Explicit definition of all the mapped documents is the only necessary
 configuration for the ODM and there are several configuration options that you
@@ -215,7 +215,7 @@ The following configuration shows a bunch of mapping examples:
         </container>
 
 Filters
-~~~~~~~
+-------
 
 Filter classes may be used in order to add criteria to ODM queries, regardless
 of where those queries are created within your application. Typically, filters
@@ -278,7 +278,7 @@ Filters may be registered with a document manager by using the following syntax:
     respectively.
 
 Multiple Connections
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 If you need multiple connections and document managers you can use the
 following syntax:
@@ -359,7 +359,7 @@ connection services:
     $dm2 = $container->get('doctrine_mongodb.odm.dm2_document_manager');
 
 Connecting to a pool of mongodb servers on 1 connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------
 
 It is possible to connect to several mongodb servers on one connection if
 you are using a replica set by listing all of the servers within the connection
@@ -394,7 +394,7 @@ Where mongodb-01, mongodb-02 and mongodb-03 are the machine hostnames. You
 can also use IP addresses if you prefer.
 
 Using Authentication on a Database Level
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------
 
 MongoDB supports authentication and authorisation on a database-level. This is mandatory if you have
 e.g. a publicly accessible MongoDB Server. To make use of this feature you need to configure credentials
@@ -496,7 +496,7 @@ You can then use this service in your configuration:
 
 
 Full Default Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 .. configuration-block::
 

Resources/doc/console.rst

@@ -0,0 +1,27 @@
+Console Commands
+================
+
+The Doctrine2 ODM integration offers several console commands under the
+``doctrine:mongodb`` namespace. To view the command list you can run the console
+without any arguments:
+
+.. code-block:: bash
+
+    php bin/console
+
+A list of available command will print out, many of which start with the
+``doctrine:mongodb`` prefix. You can find out more information about any
+of these commands (or any Symfony command) by running the ``help`` command.
+For example, to get details about the ``doctrine:mongodb:query`` task, run:
+
+.. code-block:: bash
+
+    php bin/console help doctrine:mongodb:query
+
+.. note::
+
+   To be able to load data fixtures into MongoDB, you will need to have the
+   ``DoctrineFixturesBundle`` bundle installed. To learn how to do it, read
+   the "`DoctrineFixturesBundle`_" entry of the documentation.
+
+.. _`DoctrineFixturesBundle`: http://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html

Resources/doc/form.rst → Resources/doc/cookbook/registration_form.rst

@@ -1,5 +1,5 @@
-How to implement a simple Registration Form with MongoDB
-========================================================
+Cookbook: Creating Registration Form
+====================================
 
 Some forms have extra fields whose values don't need to be stored in the
 database. In this example, we'll create a registration form with some extra

Resources/doc/events.rst

@@ -0,0 +1,81 @@
+Registering Event Listeners and Subscribers
+===========================================
+
+Doctrine allows you to register listeners and subscribers that are notified
+when different events occur inside Doctrine's ODM. For more information,
+see Doctrine's `Event Documentation`_.
+
+.. tip::
+
+    In addition to ODM events, you may also listen on lower-level MongoDB
+    events, which you'll find defined in the ``Doctrine\MongoDB\Events`` class.
+
+.. note::
+
+    Each connection in Doctrine has its own event manager, which is shared with
+    document managers tied to that connection. Listeners and subscribers may be
+    registered with all event managers or just one (using the connection name).
+
+In Symfony, you can register a listener or subscriber by creating a service
+and then `tagging`_ it with a specific tag.
+
+*   **event listener**: Use the ``doctrine_mongodb.odm.event_listener`` tag to
+    register a listener. The ``event`` attribute is required and should denote
+    the event on which to listen. By default, listeners will be registered with
+    event managers for all connections. To restrict a listener to a single
+    connection, specify its name in the tag's ``connection`` attribute.
+
+    The ``priority`` attribute, which defaults to ``0`` if omitted, may be used
+    to control the order that listeners are registered. Much like Symfony2's
+    `event dispatcher`_, greater numbers will result in the listener executing
+    first and listeners with the same priority will be executed in the order that
+    they were registered with the event manager.
+
+    Lastly, the ``lazy`` attribute, which defaults to ``false`` if omitted, may
+    be used to request that the listener be lazily loaded by the event manager
+    when its event is dispatched.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            my_doctrine_listener:
+                class:   Acme\HelloBundle\Listener\MyDoctrineListener
+                # ...
+                tags:
+                    -  { name: doctrine_mongodb.odm.event_listener, event: postPersist }
+
+    .. code-block:: xml
+
+        <service id="my_doctrine_listener" class="Acme\HelloBundle\Listener\MyDoctrineListener">
+            <!-- ... -->
+            <tag name="doctrine_mongodb.odm.event_listener" event="postPersist" />
+        </service>
+
+    .. code-block:: php
+
+        $definition = new Definition('Acme\HelloBundle\Listener\MyDoctrineListener');
+        // ...
+        $definition->addTag('doctrine_mongodb.odm.event_listener', array(
+            'event' => 'postPersist',
+        ));
+        $container->setDefinition('my_doctrine_listener', $definition);
+
+*   **event subscriber**: Use the ``doctrine_mongodb.odm.event_subscriber`` tag
+    to register a subscriber. Subscribers are responsible for implementing
+    ``Doctrine\Common\EventSubscriber`` and a method for returning the events
+    they will observe. For this reason, this tag has no ``event`` attribute;
+    however, the ``connection``, ``priority`` and ``lazy`` attributes are
+    available.
+
+.. note::
+
+    Unlike Symfony2 event listeners, Doctrine's event manager expects each
+    listener and subscriber to have a method name corresponding to the observed
+    event(s). For this reason, the aforementioned tags have no ``method``
+    attribute.
+
+.. _`event dispatcher`: http://symfony.com/doc/current/components/event_dispatcher/introduction.html
+.. _`Event Documentation`: http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/events.html
+.. _`tagging`: http://symfony.com/doc/current/book/service_container.html#book-service-container-tags