[book][page_creation] Updating the page creation chapter to be consistent with the Standard Distribution

weaverryan · weaverryan · commit b7488403a34c · 2011-03-08T20:32:18.000-06:00
This is primarily in response to the Sensio namespace being used in the Standard Distribution and being mapped to a directory in the autoloader. In order to avoid autoloading problems, it's easier to use the "Acme" namespace in our examples and map it to the ``src`` directory. The Standard Distribution does this already, so this matches it.

Additionally, the chapter needed more explanation up front about how to actually get started (in case someone is actually coding along with the tutorial). So, a section on creating the bundle was added early in the chapter. Overall, we'll see how it reads.
diff --git a/book/page_creation.rst b/book/page_creation.rst
@@ -34,15 +34,64 @@ to the following URL:
 
     http://localhost/app_dev.php/hello/Symfony
 
+In reality, you'll be able to replace ``Symfony`` with any other name to be
+greeted. To create the page, we'll go through the simple two-step process.
+
 .. note::
 
     The tutorial assumes that you've already downloaded Symfony2 and configured
     your webserver. The above URL assumes that ``localhost`` points to the
     ``web`` directory of your new Symfony2 project. For detailed information
     on this process, see the :doc:`Installing Symfony2</book/installation>`.
+    
+    If you've downloaded the `Symfony Standard Edition`_, delete the
+    ``src/Acme/DemoBundle`` directory, as you'll recreate it in this chapter.
 
-In reality, you'll be able to replace ``Symfony`` with any other name to be
-greeted. To create the page, we'll go through the simple two-step process.
+Create the Bundle
+~~~~~~~~~~~~~~~~~
+
+Before you begin, you'll need to create a *bundle*. In Symfony2, a bundle
+is like a plugin, except that all of the code in your application will live
+inside a bundle.
+
+A bundle is nothing more than a directory (with a PHP namespace) that houses
+everything related to a specific feature (see :ref:`page-creation-bundles`).
+To create a bundle called ``AcmeDemoBundle``, run the following command:
+
+.. code-block:: text
+
+    php app/console init:bundle "Acme\DemoBundle" src
+
+Next, be sure that the ``Acme`` namespace is loaded by adding the following
+to the ``app/autoload.php`` file (see the :ref:`Autoloading sidebar<autoloading-introduction-sidebar>`):
+
+.. code-block:: php
+
+        $loader->registerNamespaces(array(
+            'Acme'                         => __DIR__.'/../src',
+            // ...
+        ));
+
+Finally, initialize the bundle by adding it to the ``registerBundles`` method
+of the ``AppKernel`` class:
+
+.. code-block:: php
+
+    // app/AppKernel.php
+    public function registerBundles()
+    {
+        $bundles = array(
+            // ...
+            new Acme\DemoBundle\AcmeDemoBundle(),
+        );
+        
+        // ...
+
+        return $bundles;
+    }
+
+Now that you have a bundle setup, you can begin building your application
+inside the bundle.
 
 Create the Route
 ~~~~~~~~~~~~~~~~
@@ -61,7 +110,7 @@ you can also choose to use XML or PHP out of the box to configure routes:
             defaults: { _controller: FrameworkBundle:Default:index }
 
         hello:
-            resource: @HelloBundle/Resources/config/routing.yml
+            resource: @AcmeDemoBundle/Resources/config/routing.yml
 
     .. code-block:: xml
 
@@ -76,7 +125,7 @@ you can also choose to use XML or PHP out of the box to configure routes:
                 <default key="_controller">FrameworkBundle:Default:index</default>
             </route>
 
-            <import resource="@HelloBundle/Resources/config/routing.xml" />
+            <import resource="@AcmeDemoBundle/Resources/config/routing.xml" />
         </routes>
 
     .. code-block:: php
@@ -89,7 +138,7 @@ you can also choose to use XML or PHP out of the box to configure routes:
         $collection->add('homepage', new Route('/', array(
             '_controller' => 'FrameworkBundle:Default:index',
         )));
-        $collection->addCollection($loader->import("@HelloBundle/Resources/config/routing.php"));
+        $collection->addCollection($loader->import("@AcmeDemoBundle/Resources/config/routing.php"));
 
         return $collection;
 
@@ -103,34 +152,34 @@ inside the ``HelloBundle``:
 
     .. code-block:: yaml
 
-        # src/Sensio/HelloBundle/Resources/config/routing.yml
+        # src/Acme/DemoBundle/Resources/config/routing.yml
         hello:
             pattern:  /hello/{name}
-            defaults: { _controller: HelloBundle:Hello:index }
+            defaults: { _controller: AcmeDemoBundle:Hello:index }
 
     .. code-block:: xml
 
-        <!-- src/Sensio/HelloBundle/Resources/config/routing.xml -->
+        <!-- src/Acme/DemoBundle/Resources/config/routing.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
 
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="hello" pattern="/hello/{name}">
-                <default key="_controller">HelloBundle:Hello:index</default>
+                <default key="_controller">AcmeDemoBundle:Hello:index</default>
             </route>
         </routes>
 
     .. code-block:: php
 
-        // src/Sensio/HelloBundle/Resources/config/routing.php
+        // src/Acme/DemoBundle/Resources/config/routing.php
         use Symfony\Component\Routing\RouteCollection;
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
         $collection->add('hello', new Route('/hello/{name}', array(
-            '_controller' => 'HelloBundle:Hello:index',
+            '_controller' => 'AcmeDemoBundle:Hello:index',
         )));
 
         return $collection;
@@ -163,9 +212,9 @@ from the request to build and prepare the resource being requested. Except
 in some advanced cases, the end product of a controller is always the same:
 a Symfony2 ``Response`` object::
 
-    // src/Sensio/HelloBundle/Controller/HelloController.php
+    // src/Acme/DemoBundle/Controller/HelloController.php
 
-    namespace Sensio\HelloBundle\Controller;
+    namespace Acme\DemoBundle\Controller;
     use Symfony\Component\HttpFoundation\Response;
 
     class HelloController
@@ -201,9 +250,9 @@ Templates allows us to move all of the presentation (e.g. HTML code) into
 a separate file and reuse different portions of the page layout. Instead
 of writing the HTML inside the controller, use a template instead::
 
-    // src/Sensio/HelloBundle/Controller/HelloController.php
+    // src/Acme/DemoBundle/Controller/HelloController.php
 
-    namespace Sensio\HelloBundle\Controller;
+    namespace Acme\DemoBundle\Controller;
 
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 
@@ -246,7 +295,7 @@ controller, and ``index.html.twig`` the template:
     .. code-block:: jinja
        :linenos:
 
-        {# src/Sensio/HelloBundle/Resources/views/Hello/index.html.twig #}
+        {# src/Acme/DemoBundle/Resources/views/Hello/index.html.twig #}
         {% extends '::layout.html.twig' %}
 
         {% block body %}
@@ -255,8 +304,8 @@ controller, and ``index.html.twig`` the template:
 
     .. code-block:: php
 
-        <!-- src/Sensio/HelloBundle/Resources/views/Hello/index.html.php -->
-        <?php $view->extend('HelloBundle::layout.html.php') ?>
+        <!-- src/Acme/DemoBundle/Resources/views/Hello/index.html.php -->
+        <?php $view->extend('AcmeDemoBundle::layout.html.php') ?>
 
         Hello <?php echo $view->escape($name) ?>!
 
@@ -419,20 +468,21 @@ each of these directories in later chapters.
     behalf the instance you need a class::
     
         $loader->registerNamespaces(array(
-            'Sensio'                         => __DIR__.'/../src',
+            'Acme'                         => __DIR__.'/../src',
             // ...
         ));
     
     With this configuration, Symfony2 will look inside the ``src`` directory
-    for any class in the ``Sensio`` namespace. For autoloading to work,
-    the class name and path to the file must follow the same pattern:
+    for any class in the ``Acme`` namespace (your pretend company's namespace).
+    For autoloading to work, the class name and path to the file must follow
+    the same pattern:
 
     .. code-block:: text
 
         Class Name:
-            Sensio\HelloBundle\Controller\HelloController
+            Acme\DemoBundle\Controller\HelloController
         Path:
-            src/Sensio/HelloBundle/Controller/HelloController.php
+            src/Acme/DemoBundle/Controller/HelloController.php
 
     The ``app/autoload.php`` configures the autoloader to look for different
     PHP namespaces in different directories and can be customized as necessary.
@@ -449,6 +499,8 @@ with *bundles* that contain your application code.
 
 But what exactly is a :term:`bundle`?
 
+.. _page-creation-bundles:
+
 The Bundle System
 -----------------
 
@@ -491,7 +543,7 @@ method of the ``AppKernel`` class::
             //new Symfony\Bundle\DoctrineMongoDBBundle\DoctrineMongoDBBundle(),
 
             // register your bundles
-            new Sensio\HelloBundle\HelloBundle(),
+            new Acme\DemoBundle\AcmeDemoBundle(),
         );
 
         if (in_array($this->getEnvironment(), array('dev', 'test'))) {
@@ -507,31 +559,31 @@ are used by your application (including the core Symfony bundles).
 .. tip::
 
    A bundle can live *anywhere* as long as it can be autoloaded by Symfony2.
-   For example, if ``SensioHelloBundle`` lives inside the ``src/Sensio``
-   directory, be sure that the ``Sensio`` namespace has been added to the
+   For example, if ``AcmeDemoBundle`` lives inside the ``src/Acme``
+   directory, be sure that the ``Acme`` namespace has been added to the
    ``app/autoload.php`` file and mapped to the ``src`` directory.
 
 Creating a Bundle
 ~~~~~~~~~~~~~~~~~
 
 To show you how simple the bundle system is, let's create a new bundle called
-``SensioMyBundle`` and enable it.
+``AcmeTestBundle`` and enable it.
 
-First, create a ``src/Sensio/MyBundle/`` directory and add a new file
-called ``SensioMyBundle.php``::
+First, create a ``src/Acme/TestBundle/`` directory and add a new file
+called ``AcmeTestBundle.php``::
 
-    // src/Sensio/MyBundle/SensioMyBundle.php
-    namespace Sensio\MyBundle;
+    // src/Acme/TestBundle/AcmeTestBundle.php
+    namespace Acme\TestBundle;
 
     use Symfony\Component\HttpKernel\Bundle\Bundle;
 
-    class SensioMyBundle extends Bundle
+    class AcmeTestBundle extends Bundle
     {
     }
 
 .. tip::
 
-   The name ``SensioMyBundle`` follows the :ref:`Bundle naming conventions<bundles-naming-conventions>`.
+   The name ``AcmeTestBundle`` follows the :ref:`Bundle naming conventions<bundles-naming-conventions>`.
 
 This empty class is the only piece we need to create our new bundle. Though
 commonly empty, this class is powerful and can be used to customize the behavior
@@ -547,20 +599,21 @@ class::
             // ...
 
             // register your bundles
-            new Sensio\MyBundle\SensioMyBundle(),
+            new Acme\TestBundle\AcmeTestBundle(),
         );
 
         // ...
 
         return $bundles;
     }
 
-And while it doesn't do anything yet, ``MyBundle`` is now ready to be used.
+And while it doesn't do anything yet, ``AcmeTestBundle`` is now ready to
+be used.
 
 And as easy as this is, Symfony also provides a command-line interface for
 generating a basic bundle skeleton::
 
-    ./app/console init:bundle "Sensio\MyBundle" src
+    php app/console init:bundle "Acme\TestBundle" src
 
 The bundle skeleton generates with a basic controller, template and routing
 resource that can be customized. We'll talk more about Symfony2's command-line
@@ -576,7 +629,7 @@ Bundle Directory Structure
 
 The directory structure of a bundle is simple and flexible. By default, the
 bundle system follows a set of conventions that help to keep code consistent
-between all Symfony2 bundles. Let's take a look at ``HelloBundle``, as it
+between all Symfony2 bundles. Let's take a look at ``AcmeDemoBundle``, as it
 contains some of the most common elements of a bundle:
 
 * *Controller/* contains the controllers of the bundle (e.g. ``HelloController.php``);
@@ -884,3 +937,4 @@ Learn more from the Cookbook
 
 .. _`Twig`: http://www.twig-project.org
 .. _`third-party bundles`: http://symfony2bundles.org/
+.. _`Symfony Standard Edition`: http://symfony.com/download
diff --git a/glossary.rst b/glossary.rst
@@ -16,9 +16,10 @@ Glossary
         given set of Bundles.
 
    Bundle
-        A *Bundle* is a structured set of files (PHP files, stylesheets,
-        JavaScripts, images, ...) that *implement* a single feature (a blog,
-        a forum, ...) and which can be easily shared with other developers.
+        A *Bundle* is a directory containing a set of files (PHP files,
+        stylesheets, JavaScripts, images, ...) that *implement* a single
+        feature (a blog, a forum, etc). In Symfony2, (*almost*) everything
+        lives inside a bundle. (see :ref:`page-creation-bundles`)
 
    Front Controller
         A *Front Controller* is a short PHP that lives in the web directory
