Modernize documentation

Resources/doc/config.rst

@@ -8,7 +8,7 @@ Sample Configuration
 
     .. code-block:: yaml
 
-        # app/config/config.yml
+        # config/packages/doctrine_mongodb.yaml
         doctrine_mongodb:
             connections:
                 default:
@@ -133,7 +133,7 @@ can control. The following configuration options exist for a mapping:
   this path is relative it is assumed to be relative to the bundle root. This
   only works if the name of your mapping is a bundle name. If you want to use
   this option to specify absolute paths you should prefix the path with the
-  kernel parameters that exist in the DIC (for example %kernel.root_dir%).
+  kernel parameters that exist in the DIC (for example %kernel.project_dir%).
 
 - ``prefix`` A common namespace prefix that all documents of this mapping
   share. This prefix should never conflict with prefixes of other defined
@@ -154,14 +154,14 @@ can control. The following configuration options exist for a mapping:
 To avoid having to configure lots of information for your mappings you should
 follow these conventions:
 
-1. Put all your documents in a directory ``Document/`` inside your bundle. For
-   example ``Acme/HelloBundle/Document/``.
+1. Put all your documents in a directory ``Document/`` inside your project. For
+   example ``src/Document/``.
 
 2. If you are using xml, yml or php mapping put all your configuration files
    into the ``Resources/config/doctrine/`` directory
    suffixed with mongodb.xml, mongodb.yml or mongodb.php respectively.
 
-3. Annotations is assumed if a ``Document/`` but no
+3. Annotations are assumed if a ``Document/`` but no
    ``Resources/config/doctrine/`` directory is found.
 
 The following configuration shows a bunch of mapping examples:
@@ -184,7 +184,7 @@ The following configuration shows a bunch of mapping examples:
                             alias: BundleAlias
                         doctrine_extensions:
                             type: xml
-                            dir: "%kernel.root_dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Documents"
+                            dir: "%kernel.project_dir%/src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Documents"
                             prefix: DoctrineExtensions\Documents\
                             alias: DExt
 
@@ -207,7 +207,7 @@ The following configuration shows a bunch of mapping examples:
                     <doctrine_mongodb:mapping name="MyBundle5" type="xml" dir="my-bundle-mappings-dir" alias="BundleAlias" />
                     <doctrine_mongodb:mapping name="doctrine_extensions"
                                               type="xml"
-                                              dir="%kernel.root_dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Documents"
+                                              dir="%kernel.project_dir%/src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Documents"
                                               prefix="DoctrineExtensions\Documents\"
                                               alias="DExt" />
                 </doctrine_mongodb:document-manager>
@@ -398,8 +398,8 @@ 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
-for each of your connections. Also every connection needs a database set to authenticate against. The setting is
-represented by the *authSource* `connection string <https://docs.mongodb.com/manual/reference/connection-string/#urioption.authSource>`_.
+for each of your connections. Every connection needs also a database to authenticate against. The setting is
+represented by the *authSource* `connection string`_.
 Otherwise you will get a *auth failed* exception.
 
 .. configuration-block::
@@ -442,7 +442,8 @@ Specifying a context service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The MongoDB driver supports receiving a stream context to set SSL and logging
-options. This can be used to authenticate using SSL certificates. To do so, create a service that creates your logging context:
+options. This can be used to authenticate using SSL certificates. To do so,
+create a service that creates your logging context:
 
 .. configuration-block::
 

Resources/doc/console.rst

@@ -1,16 +1,16 @@
 Console Commands
 ================
 
-The Doctrine2 ODM integration offers several console commands under the
+The Doctrine2 ODM integration offers various 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
+A list of available commands will be printed out, several of them 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:
 
@@ -24,4 +24,4 @@ For example, to get details about the ``doctrine:mongodb:query`` task, run:
    ``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
+.. _`DoctrineFixturesBundle`: https://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html

Resources/doc/cookbook/registration_form.rst

@@ -2,19 +2,19 @@ Creating a 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
-fields and (like a "terms accepted" checkbox field) and embed the form that
-actually stores the account information. We'll use MongoDB for storing the data.
+database. In this example, we'll create a registration form with such
+field ("terms accepted" checkbox field) and embed the form that actually
+stores the account information. We'll use MongoDB for storing the data.
 
-The simple User model
+The User Model
 ---------------------
 
-So, in this tutorial we begin with the model for a ``User`` document:
+We begin this tutorial with the model for a ``User`` document:
 
 .. code-block:: php
 
-    // src/Acme/AccountBundle/Document/User.php
-    namespace Acme\AccountBundle\Document;
+    // src/Document/User.php
+    namespace App\Document;
 
     use Doctrine\Bundle\MongoDBBundle\Validator\Constraints\Unique as MongoDBUnique;
     use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;
@@ -72,8 +72,8 @@ So, in this tutorial we begin with the model for a ``User`` document:
     }
 
 This ``User`` document contains three fields and two of them (email and
-password) should display on the form. The email property must be unique
-on the database, so we've added this validation at the top of the class.
+password) should be displayed in the form. The email property must be unique
+in the database, so we've added this validation at the top of the class.
 
 .. note::
 
@@ -87,10 +87,10 @@ Next, create the form for the ``User`` model:
 
 .. code-block:: php
 
-    // src/Acme/AccountBundle/Form/Type/UserType.php
-    namespace Acme\AccountBundle\Form\Type;
+    // src/Form/Type/UserType.php
+    namespace App\Form\Type;
 
-    use Acme\AccountBundle\Document\User;
+    use App\Document\User;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\Extension\Core\Type\EmailType;
     use Symfony\Component\Form\Extension\Core\Type\PasswordType;
@@ -118,9 +118,9 @@ Next, create the form for the ``User`` model:
         }
     }
 
-We just added two fields: email and password (repeated to confirm the entered
-password). The ``data_class`` option tells the form the name of data class
-(i.e. your ``User`` document).
+We added two fields: email and password (repeated to confirm the entered
+password). The ``data_class`` option tells the form the name of the class
+that holds the underlying data (i.e. your ``User`` document).
 
 .. tip::
 
@@ -130,26 +130,25 @@ Embedding the User form into a Registration Form
 ------------------------------------------------
 
 The form that you'll use for the registration page is not the same as the
-form used to simply modify the ``User`` (i.e. ``UserType``). The registration
+form used to modify the ``User`` (i.e. ``UserType``). The registration
 form will contain further fields like "accept the terms", whose value won't be
 stored in the database.
 
 In other words, create a second form for registration, which embeds the ``User``
-form and adds the extra field needed. Start by creating a simple class which
-represents the "registration":
+form and adds the extra field needed:
 
 .. code-block:: php
 
-    // src/Acme/AccountBundle/Form/Model/Registration.php
-    namespace Acme\AccountBundle\Form\Model;
+    // src/Form/Model/Registration.php
+    namespace App\Form\Model;
 
-    use Acme\AccountBundle\Document\User;
+    use App\Document\User;
     use Symfony\Component\Validator\Constraints as Assert;
 
     class Registration
     {
         /**
-         * @Assert\Type(type="Acme\AccountBundle\Document\User")
+         * @Assert\Type(type="App\Document\User")
          */
         protected $user;
 
@@ -184,8 +183,8 @@ Next, create the form for this ``Registration`` model:
 
 .. code-block:: php
 
-    // src/Acme/AccountBundle/Form/Type/RegistrationType.php
-    namespace Acme\AccountBundle\Form\Type;
+    // src/Form/Type/RegistrationType.php
+    namespace App\Form\Type;
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType
@@ -200,34 +199,35 @@ Next, create the form for this ``Registration`` model:
         }
     }
 
-You don't need to use special method for embedding the ``UserType`` form.
-A form is a field, too - so you can add this like any other field, with the
+You don't need to use any special method to embed the ``UserType`` form.
+A form is a field, too - you can add it like any other field, with the
 expectation that the corresponding ``user`` property will hold an instance
 of the class ``UserType``.
 
 Handling the Form Submission
 ----------------------------
 
-Next, you need a controller to handle the form. Start by creating a simple
-controller for displaying the registration form:
+Next, you need a controller to handle the form. Start by creating a
+controller that will display the registration form:
 
 .. code-block:: php
 
-    // src/Acme/AccountBundle/Controller/AccountController.php
-    namespace Acme\AccountBundle\Controller;
+    // src/Controller/AccountController.php
+    namespace App\Controller;
 
-    use Acme\AccountBundle\Form\Model\Registration;
-    use Acme\AccountBundle\Form\Type\RegistrationType;
+    use Doctrine\ODM\MongoDB\DocumentManager;
+    use App\Form\Model\Registration;
+    use App\Form\Type\RegistrationType;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     use Symfony\Component\HttpFoundation\Response;
 
-    class AccountController extends Controller
+    class AccountController extends AbstractController
     {
         public function registerAction()
         {
             $form = $this->createForm(RegistrationType::class, new Registration());
 
-            return $this->render('AcmeAccountBundle:Account:register.html.twig', [
+            return $this->render('Account/register.html.twig', [
                 'form' => $form->createView()
             ]);
         }
@@ -237,18 +237,20 @@ and its template:
 
 .. code-block:: html+jinja
 
-    {# src/Acme/AccountBundle/Resources/views/Account/register.html.twig #}
+    {# templates/Account/register.html.twig #}
+
     {{ form_start(form, {'action': path('create'), 'method': 'POST'}) }}
         {{ form_widget(form) }}
 
         <input type="submit" />
     {{ form_end(form) }}
 
-Finally, create the controller which handles the form submission.  This performs
-the validation and saves the data into MongoDB:
+Finally, create another action in ``AccountController``, which will handle
+the form submission - perform its validation and save the User into MongoDB:
 
 .. code-block:: php
 
+    // src/Controller/AccountController.php
     public function createAction(DocumentManager $dm, Request $request)
     {
         $form = $this->createForm(RegistrationType::class, new Registration());
@@ -264,13 +266,13 @@ the validation and saves the data into MongoDB:
             return $this->redirect(...);
         }
 
-        return $this->render('AcmeAccountBundle:Account:register.html.twig', [
+        return $this->render('Account/register.html.twig', [
             'form' => $form->createView()
         ]);
     }
 
-That's it! Your form now validates, and allows you to save the ``User``
-object to MongoDB.
+That's it! Your form now validates sent data and allows you to save
+the ``User`` object to MongoDB.
 
 .. _`UserInterface`: http://symfony.com/doc/current/book/security.html#book-security-user-entity
 .. _`file`: http://symfony.com/doc/current/book/forms.html

Resources/doc/events.rst

@@ -24,8 +24,8 @@ 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 Symfony's
-`event dispatcher`_, greater numbers will result in the listener executing
+to control the order in which listeners are registered. Much like Symfony's
+`event dispatcher`_, greater number 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.
 
@@ -39,21 +39,21 @@ when its event is dispatched.
 
         services:
             my_doctrine_listener:
-                class:   Acme\HelloBundle\Listener\MyDoctrineListener
+                class:   App\Listener\MyDoctrineListener
                 # ...
                 tags:
                     -  { name: doctrine_mongodb.odm.event_listener, event: postPersist }
 
     .. code-block:: xml
 
-        <service id="my_doctrine_listener" class="Acme\HelloBundle\Listener\MyDoctrineListener">
+        <service id="my_doctrine_listener" class="App\Listener\MyDoctrineListener">
             <!-- ... -->
             <tag name="doctrine_mongodb.odm.event_listener" event="postPersist" />
         </service>
 
     .. code-block:: php
 
-        $definition = new Definition('Acme\HelloBundle\Listener\MyDoctrineListener');
+        $definition = new Definition('App\Listener\MyDoctrineListener');
         // ...
         $definition->addTag('doctrine_mongodb.odm.event_listener', [
             'event' => 'postPersist',
@@ -64,11 +64,11 @@ Event Subscribers
 -----------------
 
 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.
+to register a subscriber. Subscribers must implement interface
+``Doctrine\Common\EventSubscriber``, which means that they must
+contain method 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::
 
@@ -77,6 +77,6 @@ available.
     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
+.. _`event dispatcher`: https://symfony.com/doc/current/components/event_dispatcher.html
+.. _`Event Documentation`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/events.html
 .. _`tagging`: https://symfony.com/doc/current/service_container/tags.html