Modernize documentation

Resources/doc/config.rst

@@ -161,7 +161,7 @@ follow these conventions:
    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:
@@ -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,14 +2,14 @@ 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
 
@@ -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::
 
@@ -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,13 +130,12 @@ 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
 
@@ -200,16 +199,16 @@ 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
 
@@ -244,8 +243,8 @@ and its template:
         <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
 
@@ -269,8 +268,8 @@ the validation and saves the data into MongoDB:
         ]);
     }
 
-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.
 
@@ -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

Resources/doc/first_steps.rst

@@ -38,9 +38,9 @@ inside the ``Document`` directory of your ``AcmeStoreBundle``:
     }
 
 The class - often called a "document", meaning *a basic class that holds data* -
-is simple and helps fulfill the business requirement of needing products
-in your application. This class can't be persisted to Doctrine MongoDB yet -
-it's just a simple PHP class.
+helps fulfill the business requirement of needing products in your application.
+This class can't be persisted to Doctrine MongoDB yet - currently it's
+only plain PHP class.
 
 Add Mapping Information
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -51,8 +51,8 @@ you to persist entire *objects* to MongoDB and fetch entire objects out of
 MongoDB. This works by mapping a PHP class and its properties to entries
 of a MongoDB collection.
 
-For Doctrine to be able to do this, you just have to create "metadata", or
-configuration that tells Doctrine exactly how the ``Product`` class and its
+For Doctrine to be able to do this, you have to create "metadata", or
+configuration, that tells Doctrine exactly how the ``Product`` class and its
 properties should be *mapped* to MongoDB. This metadata can be specified
 in a number of different formats including XML or directly inside the
 ``Product`` class via annotations:
@@ -115,9 +115,8 @@ Persisting Objects to MongoDB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now that you have a mapped ``Product`` document complete with getter and
-setter methods, you're ready to persist data to MongoDB. From inside a controller,
-this is pretty easy. Add the following method to the ``DefaultController``
-of the bundle:
+setter methods, you're ready to persist data to MongoDB. Let's try it from inside
+a controller. Create new Controller class inside source directory of your project:
 
 .. code-block:: php
     :linenos:
@@ -202,14 +201,14 @@ they already exist in MongoDB.
 .. tip::
 
     Doctrine provides a library that allows you to programmatically load testing
-    data into your project (i.e. "fixture data"). For information, see
+    data into your project (i.e. "fixture data"). For more information, see
     `DoctrineFixturesBundle`_.
 
 Fetching Objects from MongoDB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Fetching an object back out of MongoDB is even easier. For example, suppose
-you've configured a route to display a specific ``Product`` based on its
+Fetching an object back out of MongoDB is also possible. For example, suppose
+that you've configured a route to display a specific ``Product`` based on its
 ``id`` value:
 
 .. code-block:: php
@@ -260,8 +259,8 @@ Once you have your repository, you have access to all sorts of helpful methods:
 
 .. note::
 
-    Of course, you can also issue complex queries, which you'll learn more
-    about in the `Querying for Objects`_ section.
+    You can also issue complex queries, you can learn more about them
+    in the `Querying for Objects`_ section.
 
 You can also take advantage of the useful ``findBy()`` and ``findOneBy()`` methods
 to easily fetch objects based on multiple conditions:
@@ -280,7 +279,7 @@ to easily fetch objects based on multiple conditions:
 Updating an Object
 ~~~~~~~~~~~~~~~~~~
 
-Once you've fetched an object from Doctrine, updating it is easy. Suppose
+Once you've fetched an object from Doctrine, let's try to update it. Suppose
 you have a route that maps a product id to an update action in a controller:
 
 .. code-block:: php
@@ -299,14 +298,14 @@ you have a route that maps a product id to an update action in a controller:
         return $this->redirectToRoute('homepage');
     }
 
-Updating an object involves just three steps:
+Updating an object involves three steps:
 
 1. Fetching the object from Doctrine;
 2. Modifying the object;
 3. Calling ``flush()`` on the document manager.
 
 Notice that calling ``$dm->persist($product)`` isn't necessary. Recall that
-this method simply tells Doctrine to manage or "watch" the ``$product`` object.
+this method tells Doctrine to manage or "watch" the ``$product`` object.
 In this case, since you fetched the ``$product`` object from Doctrine, it's
 already managed.
 
@@ -321,16 +320,16 @@ method of the document manager:
     $dm->remove($product);
     $dm->flush();
 
-As you might expect, the ``remove()`` method notifies Doctrine that you'd
-like to remove the given document from the MongoDB. The actual delete operation
-however, isn't actually executed until the ``flush()`` method is called.
+The ``remove()`` method notifies Doctrine that you'd like to remove
+the given document from the MongoDB. The actual delete operation
+however, isn't executed until the ``flush()`` method is called.
 
 Querying for Objects
 --------------------
 
 As you saw above, the built-in repository class allows you to query for one
-or many objects based on an number of different parameters. When this is
-enough, this is the easiest way to query for documents. Of course, you can
+or many objects based on any number of different parameters. When this is
+enough, this is the recommended way to query for documents. Of course, you can
 also create more complex queries.
 
 Using the Query Builder
@@ -425,7 +424,7 @@ for all of the ``Product`` documents, ordered alphabetically.
         }
     }
 
-You can use this new method just like the default finder methods of the repository:
+You can use this new method like the default finder methods of the repository:
 
 .. code-block:: php
 
@@ -497,9 +496,9 @@ repositories as services you can use the following service configuration:
             </services>
         </container>
 
-.. _`Basic Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/basic-mapping.html
-.. _`Conditional Operators`: http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/query-builder-api.html#conditional-operators
-.. _`DoctrineFixturesBundle`: http://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html
-.. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/query-builder-api.html
+.. _`Basic Mapping Documentation`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/basic-mapping.html
+.. _`Conditional Operators`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/query-builder-api.html#conditional-operators
+.. _`DoctrineFixturesBundle`: https://symfony.com/doc/master/bundles/DoctrineFixturesBundle/index.html
+.. _`Query Builder`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/query-builder-api.html
 .. _`autowiring`: https://symfony.com/doc/current/service_container/autowiring.html
 .. _`autoconfiguration`: https://symfony.com/doc/current/service_container.html#the-autoconfigure-option

Resources/doc/form_validation.rst

@@ -22,4 +22,4 @@ means that the ``em`` option should be used if you wish to specify the document
 manager explicitly instead of having it be inferred from the document class.
 
 .. _`EntityType`: https://symfony.com/doc/current/reference/forms/types/entity.html
-.. _`UniqueEntity`: http://symfony.com/doc/current/reference/constraints/UniqueEntity.html
+.. _`UniqueEntity`: https://symfony.com/doc/current/reference/constraints/UniqueEntity.html

Resources/doc/index.rst

@@ -10,15 +10,15 @@ persisted transparently to and from MongoDB.
 
     You can read more about the Doctrine MongoDB ODM via the project's `documentation`_.
 
-A bundle is available that integrates the Doctrine MongoDB ODM into Symfony,
-making it easy to configure and use.
+The bundle integrates the Doctrine MongoDB ODM into Symfony,
+helping you to configure and use it in your application.
 
 .. note::
 
     This documentation will feel a lot like the `Doctrine2 ORM chapter`_,
     which talks about how the Doctrine ORM can be used to persist data to
     relational databases (e.g. MySQL). This is on purpose - whether you persist
-    to a relational database via the ORM or MongoDB via the ODM, the philosophies
+    to a relational database via the ORM or to MongoDB via the ODM, the philosophies
     are very much the same.
 
 .. toctree::
@@ -36,15 +36,16 @@ Doctrine Extensions: Timestampable, Sluggable, etc.
 ---------------------------------------------------
 
 Doctrine is quite flexible, and a number of third-party extensions are available
-that allow you to easily perform repeated and common tasks on your entities.
-These include thing such as *Sluggable*, *Timestampable*, *Loggable*, *Translatable*,
+that allow you to perform repeated and common tasks on your entities.
+These include things such as *Sluggable*, *Timestampable*, *Loggable*, *Translatable*,
 and *Tree*.
 
-For more information on how to find and use these extensions, see the cookbook
-article about `using common Doctrine extensions`_.
+For more information about them, see `available Doctrine extensions`_
+and use the `StofDoctrineExtensionsBundle`_ to integrate them in your application.
 
-.. _`MongoDB`: http://www.mongodb.org/
-.. _`Doctrine2 ORM`: http://symfony.com/doc/current/book/doctrine.html
-.. _`documentation`: http://docs.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/
-.. _`Doctrine2 ORM chapter`: http://symfony.com/doc/current/book/doctrine.html
-.. _`using common Doctrine extensions`: http://symfony.com/doc/current/cookbook/doctrine/common_extensions.html
+.. _`MongoDB`: https://www.mongodb.com
+.. _`Doctrine2 ORM`: https://symfony.com/doc/current/book/doctrine.html
+.. _`documentation`: https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/
+.. _`Doctrine2 ORM chapter`: https://symfony.com/doc/current/book/doctrine.html
+.. _`available Doctrine extensions`: https://github.com/Atlantic18/DoctrineExtensions
+.. _`StofDoctrineExtensionsBundle`: https://symfony.com/doc/current/bundles/StofDoctrineExtensionsBundle/index.html