[cookbook][doctrine][fixtures] Finishing doctrine fixtures proofreading

Author: weaverryan

cookbook/doctrine/doctrine_fixtures.rst

@@ -4,8 +4,8 @@
 How to create Fixtures in Symfony2
 ==================================
 
-Fixtures are used to load the database with a set of data. This data can
-either be for testing or could be the initial data required for the
+Fixtures are used to load a controlled set of data into a database. This
+data can be used for testing or could be the initial data required for the
 application to run smoothly. Symfony2 has no built in way to manage fixtures
 but Doctrine2 has a library to help you write fixtures for the Doctrine
 :doc:`ORM</book/doctrine/orm/overview>` or :doc:`ODM</book/doctrine/mongodb-odm/overview>`.
@@ -53,10 +53,15 @@ come first.
 Writing Simple Fixtures
 -----------------------
 
-The ideal place to store your fixtures is inside
-``src/VendorName/MyBundle/DataFixtures/ORM`` and ``src/VendorName/MyBundle/DataFixtures/ODM``
-respectively for the ORM and ODM. This tutorial assumes that you are using
-the ORM - but fixtures can be added just as easily if you're using the ODM.
+Doctrine2 fixtures are PHP classes where you can create objects and persist
+them to the database. Like all classes in Symfony2, fixtures should live inside
+one of your application bundles.
+
+For a bundle located at ``src/VendorName/MyBundle``, the fixture classes
+should live inside ``src/VendorName/MyBundle/DataFixtures/ORM`` or
+``src/VendorName/MyBundle/DataFixtures/ODM`` respectively for the ORM and ODM,
+This tutorial assumes that you are using the ORM - but fixtures can be added
+just as easily if you're using the ODM.
 
 Imagine that you have a ``User`` class, and you'd like to load one ``User``
 entry:
@@ -85,17 +90,17 @@ entry:
     }
 
 In Doctrine2, fixtures are just objects where you load data by interacting
-with your entities as you normal do. This allows you to create the exact
-fixtures you want for your application.
+with your entities as you normally do. This allows you to create the exact
+fixtures you need for your application.
 
-The most serious limitation is that you can not share objects between fixtures.
+The most serious limitation is that you cannot share objects between fixtures.
 Later, you'll see how to overcome this limitation.
 
 Executing Fixtures
 ------------------
 
-Once your fixtures have been written, you load the fixtures via the command
-line via the ``doctrine:data:load`` command:
+Once your fixtures have been written, you can load them via the command
+line by using the ``doctrine:data:load`` command:
 
 .. code-block:: bash
 
@@ -117,7 +122,7 @@ Both commands come with a few options:
   directory or file where the fixtures classes should be loaded;
 
 * ``--append`` - Use this flag to append data instead of deleting data before
-  loading it (the default behavior);
+  loading it (deleting first is the default behavior);
 
 * ``--em=manager_name`` - Manually specify the entity manager to use for
   loading the data.
@@ -127,7 +132,7 @@ Both commands come with a few options:
    If using the ``doctrine:mongodb:data:load`` task, replace the ``--em=``
    option with ``--dm=`` to manually specify the document manager.
 
-A full example use might look like:
+A full example use might look like this:
 
 .. code-block:: bash
 
@@ -136,16 +141,23 @@ A full example use might look like:
 Sharing Objects between Fixtures
 --------------------------------
 
+Writing a basic fixture is simple. But what if you have multiple fixture classes
+and want to be able to refer to the data loaded in other fixture classes?
+For example, what if you load a ``User`` object in one fixture, and then
+want to refer to reference it in a different fixture in order to assign that
+user to a particular group?
+
+The Doctrine fixtures library handles this easily by allowing you to specify
+the order in which fixtures are loaded.
+
 .. code-block:: php
 
-    <?php
-    
-    //Vendor/MyBundle/DataFixtures/ORM/LoadUserData.php
-    namespace Vendor\MyBundle\DataFixtures\ORM;
+    // src/VendorName/MyBundle/DataFixtures/ORM/LoadUserData.php
+    namespace VendorName\MyBundle\DataFixtures\ORM;
 
     use Doctrine\Common\DataFixtures\AbstractFixture;
     use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
-    use Vendor\MyBundle\Entity\User; //Modify this to use your entity
+    use VendorName\MyBundle\Entity\User;
 
     class LoadUserData extends AbstractFixture implements OrderedFixtureInterface
     {
@@ -167,17 +179,19 @@ Sharing Objects between Fixtures
         }    
     }
 
+The fixture class now implements ``OrderedFixtureInterface``, which tells
+Doctrine that you want to control the order of your fixtures. Create another
+fixture class and make it load after ``LoadUserData`` by returning an order
+of 2:
 
 .. code-block:: php
 
-    <?php
-    
-    //Vendor/MyBundle/DataFixtures/ORM/LoadGroupData.php
-    namespace Vendor\MyBundle\DataFixtures\ORM;
+    // src/VendorName/MyBundle/DataFixtures/ORM/LoadGroupData.php
+    namespace VendorName\MyBundle\DataFixtures\ORM;
 
     use Doctrine\Common\DataFixtures\AbstractFixture;
     use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
-    use Vendor\MyBundle\Entity\Group; //Modify this to use your entity
+    use VendorName\MyBundle\Entity\Group;
 
     class LoadGroupData extends AbstractFixture implements OrderedFixtureInterface
     {
@@ -198,16 +212,20 @@ Sharing Objects between Fixtures
         }    
     }
 
+Both of the fixture classes extend ``AbstractFixture``, which allows you
+to create objects and then set them as references so that they can be used
+later in other fixtures. For example, the ``$userAdmin`` and ``$groupAdmin``
+objects can be referenced later via the ``admin-user`` and ``admin-group``
+references:
+
 .. code-block:: php
 
-    <?php
-    
-    //Vendor/MyBundle/DataFixtures/ORM/LoadUserGroupData.php
-    namespace Vendor\MyBundle\DataFixtures\ORM;
+    // src/VendorName/MyBundle/DataFixtures/ORM/LoadUserGroupData.php
+    namespace VendorName\MyBundle\DataFixtures\ORM;
 
     use Doctrine\Common\DataFixtures\AbstractFixture;
     use Doctrine\Common\DataFixtures\OrderedFixtureInterface;
-    use Vendor\MyBundle\Entity\UserGroup; //Modify this to use your entity
+    use VendorName\MyBundle\Entity\UserGroup;
     
     class LoadUserGroupData extends AbstractFixture implements OrderedFixtureInterface
     {
@@ -223,14 +241,17 @@ Sharing Objects between Fixtures
 
         public function getOrder()
         {
-            return 3; // the order in which fixtures will be loaded
+            return 3;
         }    
     }
 
-A brief explanation on how this works.
+The fixtures will now be executed in the ascending order of the value returned
+by ``getOrder()``. Any object that is set with the ``setReference()`` method
+can be accessed via ``getReference()`` in fixture classes that have a higher
+order.
 
-The fixtures will be executed in the ascending order of the value returned by
-``getOrder()``. Any object that is set with the ``setReference`` method and
-can be accessed via ``getReference`` in fixtures, which are of higher order.
+Fixtures allow you to create any type of data you need via the normal PHP
+interface for creating and persisting objects. By controlling the order of
+fixtures and setting references, almost anything can be handled by fixtures.
 
-.. _`Doctrine Data Fixtures`: https://github.com/doctrine/data-fixtures
+.. _`Doctrine Data Fixtures`: https://github.com/doctrine/data-fixtures