Made propel chapter best-practices-compatible and lots of other fixes

Author: wouterj

Diff for: best_practices/configuration.rst

@@ -42,6 +42,8 @@ they have nothing to do with the application's behavior. In other words, your
 application doesn't care about the location of your database or the credentials
 to access to it, as long as the database is correctly configured.
 
+.. _best-practices-canonical-parameters:
+
 Canonical Parameters
 ~~~~~~~~~~~~~~~~~~~~
 

Diff for: book/propel.rst

@@ -15,15 +15,6 @@ A Simple Example: A Product
 In this section, you'll configure your database, create a ``Product`` object,
 persist it to the database and fetch it back out.
 
-.. sidebar:: Code along with the Example
-
-    If you want to follow along with the example in this chapter, create an
-    AcmeStoreBundle via:
-
-    .. code-block:: bash
-
-        $ php app/console generate:bundle --namespace=Acme/StoreBundle
-
 Configuring the Database
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -42,12 +33,6 @@ information. By convention, this information is usually configured in an
         database_password: password
         database_charset:  UTF8
 
-.. note::
-
-    Defining the configuration via ``parameters.yml`` is just a convention. The
-    parameters defined in that file are referenced by the main configuration
-    file when setting up Propel:
-
 These parameters defined in ``parameters.yml`` can now be included in the
 configuration file (``config.yml``):
 
@@ -60,7 +45,13 @@ configuration file (``config.yml``):
             password: "%database_password%"
             dsn:      "%database_driver%:host=%database_host%;dbname=%database_name%;charset=%database_charset%"
 
-Now that Propel knows about your database, Symfony can create the database for
+.. note::
+
+    Defining the configuration via ``parameters.yml`` is a
+    :ref:`Symfony Framework Best Practice <best-practices-canonical-parameters>`,
+    feel free to do it differently if that suits your application better.
+
+Now that Propel knows about your database, it can create the database for
 you:
 
 .. code-block:: bash
@@ -70,8 +61,8 @@ you:
 .. note::
 
     In this example, you have one configured connection, named ``default``. If
-    you want to configure more than one connection, read the `PropelBundle
-    configuration section`_.
+    you want to configure more than one connection, read the
+    `PropelBundle configuration section`_.
 
 Creating a Model Class
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -86,14 +77,15 @@ generated by Propel contain some business logic.
 
 Suppose you're building an application where products need to be displayed.
 First, create a ``schema.xml`` file inside the ``Resources/config`` directory
-of your AcmeStoreBundle:
+of your AppBundle:
 
 .. code-block:: xml
 
+    <!-- src/AppBundle/Resources/config/schema.xml -->
     <?xml version="1.0" encoding="UTF-8" ?>
     <database
         name="default"
-        namespace="Acme\StoreBundle\Model"
+        namespace="AppBundle\Model"
         defaultIdMethod="native">
 
         <table name="product">
@@ -129,7 +121,7 @@ After creating your ``schema.xml``, generate your model from it by running:
     $ php app/console propel:model:build
 
 This generates each model class to quickly develop your application in the
-``Model/`` directory of the AcmeStoreBundle bundle.
+``Model/`` directory of the AppBundle bundle.
 
 Creating the Database Tables/Schema
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -150,32 +142,39 @@ match the schema you've specified.
 .. tip::
 
     You can run the last three commands combined by using the following
-    command: ``php app/console propel:build --insert-sql``.
+    command:
+
+    .. code-block:: bash
+    
+        $ php app/console propel:build --insert-sql
 
 Persisting Objects to the Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now that you have a ``Product`` object and corresponding ``product`` table,
 you're ready to persist data to the database. From inside a controller, this
-is pretty easy. Add the following method to the ``DefaultController`` of the
+is pretty easy. Add the following method to the ``ProductController`` of the
 bundle::
 
-    // src/Acme/StoreBundle/Controller/DefaultController.php
+    // src/AppBundle/Controller/ProductController.php
 
     // ...
-    use Acme\StoreBundle\Model\Product;
+    use AppBundle\Model\Product;
     use Symfony\Component\HttpFoundation\Response;
 
-    public function createAction()
+    class ProductController extends Controller
     {
-        $product = new Product();
-        $product->setName('A Foo Bar');
-        $product->setPrice(19.99);
-        $product->setDescription('Lorem ipsum dolor');
+        public function createAction()
+        {
+            $product = new Product();
+            $product->setName('A Foo Bar');
+            $product->setPrice(19.99);
+            $product->setDescription('Lorem ipsum dolor');
 
-        $product->save();
+            $product->save();
 
-        return new Response('Created product id '.$product->getId());
+            return new Response('Created product id '.$product->getId());
+        }
     }
 
 In this piece of code, you instantiate and work with the ``$product`` object.
@@ -194,21 +193,27 @@ Fetching an object back from the database is even easier. For example, suppose
 you've configured a route to display a specific ``Product`` based on its ``id``
 value::
 
+    // src/AppBundle/Controller/ProductController.php
+
     // ...
-    use Acme\StoreBundle\Model\ProductQuery;
+    use AppBundle\Model\ProductQuery;
 
-    public function showAction($id)
+    class ProductController extends Controller
     {
-        $product = ProductQuery::create()
-            ->findPk($id);
+        // ...
 
-        if (!$product) {
-            throw $this->createNotFoundException(
-                'No product found for id '.$id
-            );
-        }
+        public function showAction($id)
+        {
+            $product = ProductQuery::create()->findPk($id);
+
+            if (!$product) {
+                throw $this->createNotFoundException(
+                    'No product found for id '.$id
+                );
+            }
 
-        // ... do something, like pass the $product object into a template
+            // ... do something, like pass the $product object into a template
+        }
     }
 
 Updating an Object
@@ -217,31 +222,37 @@ Updating an Object
 Once you've fetched an object from Propel, updating it is easy. Suppose you
 have a route that maps a product id to an update action in a controller::
 
+    // src/AppBundle/Controller/ProductController.php
+
     // ...
-    use Acme\StoreBundle\Model\ProductQuery;
+    use AppBundle\Model\ProductQuery;
 
-    public function updateAction($id)
+    class ProductController extends Controller
     {
-        $product = ProductQuery::create()
-            ->findPk($id);
+        // ...
 
-        if (!$product) {
-            throw $this->createNotFoundException(
-                'No product found for id '.$id
-            );
-        }
+        public function updateAction($id)
+        {
+            $product = ProductQuery::create()->findPk($id);
 
-        $product->setName('New product name!');
-        $product->save();
+            if (!$product) {
+                throw $this->createNotFoundException(
+                    'No product found for id '.$id
+                );
+            }
 
-        return $this->redirect($this->generateUrl('homepage'));
+            $product->setName('New product name!');
+            $product->save();
+
+            return $this->redirect($this->generateUrl('homepage'));
+        }
     }
 
 Updating an object involves just three steps:
 
-#. fetching the object from Propel (line 6 - 13);
-#. modifying the object (line 15);
-#. saving it (line 16).
+#. fetching the object from Propel (line 12 - 18);
+#. modifying the object (line 20);
+#. saving it (line 21).
 
 Deleting an Object
 ~~~~~~~~~~~~~~~~~~
@@ -257,16 +268,22 @@ Querying for Objects
 Propel provides generated ``Query`` classes to run both basic and complex queries
 without any work::
 
-    \Acme\StoreBundle\Model\ProductQuery::create()->findPk($id);
+    use AppBundle\Model\ProductQuery;
+    // ...
+    
+    ProductQuery::create()->findPk($id);
 
-    \Acme\StoreBundle\Model\ProductQuery::create()
+    ProductQuery::create()
         ->filterByName('Foo')
         ->findOne();
 
 Imagine that you want to query for products which cost more than 19.99, ordered
 from cheapest to most expensive. From inside a controller, do the following::
 
-    $products = \Acme\StoreBundle\Model\ProductQuery::create()
+    use AppBundle\Model\ProductQuery;
+    // ...
+
+    $products = ProductQuery::create()
         ->filterByPrice(array('min' => 19.99))
         ->orderByPrice()
         ->find();
@@ -279,20 +296,26 @@ abstraction layer.
 If you want to reuse some queries, you can add your own methods to the
 ``ProductQuery`` class::
 
-    // src/Acme/StoreBundle/Model/ProductQuery.php
+    // src/AppBundle/Model/ProductQuery.php
+
+    // ...
     class ProductQuery extends BaseProductQuery
     {
         public function filterByExpensivePrice()
         {
-            return $this
-                ->filterByPrice(array('min' => 1000));
+            return $this->filterByPrice(array(
+                'min' => 1000,
+            ));
         }
     }
 
-But note that Propel generates a lot of methods for you and a simple
+However, note that Propel generates a lot of methods for you and a simple
 ``findAllOrderedByName()`` can be written without any effort::
 
-    \Acme\StoreBundle\Model\ProductQuery::create()
+    use AppBundle\Model\ProductQuery;
+    // ...
+    
+    ProductQuery::create()
         ->orderByName()
         ->find();
 
@@ -310,7 +333,7 @@ Start by adding the ``category`` definition in your ``schema.xml``:
     <?xml version="1.0" encoding="UTF-8" ?>
     <database
         name="default"
-        namespace="Acme\StoreBundle\Model"
+        namespace="AppBundle\Model"
         defaultIdMethod="native">
 
         <table name="product">
@@ -382,12 +405,14 @@ Saving Related Objects
 
 Now, try the code in action. Imagine you're inside a controller::
 
+    // src/AppBundle/Controller/ProductController.php
+
     // ...
-    use Acme\StoreBundle\Model\Category;
-    use Acme\StoreBundle\Model\Product;
+    use AppBundle\Model\Category;
+    use AppBundle\Model\Product;
     use Symfony\Component\HttpFoundation\Response;
 
-    class DefaultController extends Controller
+    class ProductController extends Controller
     {
         public function createProductAction()
         {
@@ -418,21 +443,25 @@ Fetching Related Objects
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you need to fetch associated objects, your workflow looks just like it did
-before. First, fetch a ``$product`` object and then access its related
-``Category``::
+before: Fetch a ``$product`` object and then access its related ``Category``::
+
+    // src/AppBundle/Controller/ProductController.php
 
     // ...
-    use Acme\StoreBundle\Model\ProductQuery;
+    use AppBundle\Model\ProductQuery;
 
-    public function showAction($id)
+    class ProductController extends Controller
     {
-        $product = ProductQuery::create()
-            ->joinWithCategory()
-            ->findPk($id);
+        public function showAction($id)
+        {
+            $product = ProductQuery::create()
+                ->joinWithCategory()
+                ->findPk($id);
 
-        $categoryName = $product->getCategory()->getName();
+            $categoryName = $product->getCategory()->getName();
 
-        // ...
+            // ...
+        }
     }
 
 Note, in the above example, only one query was made.
@@ -454,14 +483,14 @@ inserted, updated, deleted, etc).
 
 To add a hook, just add a new method to the object class::
 
-    // src/Acme/StoreBundle/Model/Product.php
+    // src/AppBundle/Model/Product.php
 
     // ...
     class Product extends BaseProduct
     {
         public function preInsert(\PropelPDO $con = null)
         {
-            // do something before the object is inserted
+            // ... do something before the object is inserted
         }
     }
 
@@ -488,8 +517,8 @@ Behaviors
 ---------
 
 All bundled behaviors in Propel are working with Symfony. To get more
-information about how to use Propel behaviors, look at the `Behaviors reference
-section`_.
+information about how to use Propel behaviors, look at the
+`Behaviors reference section`_.
 
 Commands
 --------