Reviewed the Bundles cookbook articles

symfony · weaverryan · Jun 9, 2015 · Mar 19, 2015 · Mar 19, 2015 · Mar 25, 2015
commit 8254761eab95870a735d8281ab1b615fbfd66372
diff --git a/cookbook/bundles/best_practices.rst b/cookbook/bundles/best_practices.rst
@@ -4,7 +4,7 @@
 Best Practices for Reusable Bundles
 ===================================
 
-There are 2 types of bundles:
+There are two types of bundles:
 
 * Application-specific bundles: only used to build your application;
 * Reusable bundles: meant to be shared across many projects.
@@ -13,12 +13,8 @@ This article is all about how to structure your **reusable bundles** so that
 they're easy to configure and extend. Many of these recommendations do not
 apply to application bundles because you'll want to keep those as simple
 as possible. For application bundles, just follow the practices shown throughout
-the book and cookbook.
-
-.. seealso::
-
-    The best practices for application-specific bundles are discussed in
-    :doc:`/best_practices/introduction`.
+the :doc:`book </book/index>`, the :doc:`cookbook </cookbook/index>` and the
+:doc:`best practices </best_practices/index>` book.
 
 .. index::
    pair: Bundle; Naming conventions
@@ -38,7 +34,7 @@ bundle class name must follow these simple rules:
 
 * Use only alphanumeric characters and underscores;
 * Use a CamelCased name;
-* Use a descriptive and short name (no more than 2 words);
+* Use a descriptive and short name (no more than two words);
 * Prefix the name with the concatenation of the vendor (and optionally the
   category namespaces);
 * Suffix the name with ``Bundle``.
@@ -112,7 +108,7 @@ The following files are mandatory:
     structure to work.
 
 The depth of sub-directories should be kept to the minimal for most used
-classes and files (2 levels at a maximum). More levels can be defined for
+classes and files (two levels at a maximum). More levels can be defined for
 non-strategic, less-used files.
 
 The bundle directory is read-only. If you need to write temporary files, store
@@ -158,7 +154,7 @@ instance, a ``HelloController`` controller is stored in
 ``Bundle/HelloBundle/Controller/HelloController.php`` and the fully qualified
 class name is ``Bundle\HelloBundle\Controller\HelloController``.
 
-All classes and files must follow the Symfony coding :doc:`standards </contributing/code/standards>`.
+All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
 
 Some classes should be seen as facades and should be as short as possible, like
 Commands, Helpers, Listeners, and Controllers.
@@ -181,7 +177,7 @@ Tests
 -----
 
 A bundle should come with a test suite written with PHPUnit and stored under
-the ``Tests/`` directory. Tests should follow the following principles:
+the ``Tests/`` directory. Tests should follow these principles:
 
 * The test suite must be executable with a simple ``phpunit`` command run from
   a sample application;
@@ -190,13 +186,14 @@ the ``Tests/`` directory. Tests should follow the following principles:
 * The tests should cover at least 95% of the code base.
 
 .. note::
+
    A test suite must not contain ``AllTests.php`` scripts, but must rely on the
    existence of a ``phpunit.xml.dist`` file.
 
 Documentation
 -------------
 
-All classes and functions must come with full PHPDoc.
+All classes and functions must be fully documented using `phpDocumentor`_ tags.
 
 Extensive documentation should also be provided in the
 :doc:`reStructuredText </contributing/documentation/format>` format, under
@@ -306,9 +303,6 @@ following standardized instructions in your ``README.md`` file.
 
         .. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
 
-This template assumes that your bundle is in its ``1.x`` version. If not, change
-the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)
-
 Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
 explain other required installation tasks, such as registering routes or
 dumping assets.
@@ -330,7 +324,8 @@ Translation Files
 -----------------
 
 If a bundle provides message translations, they must be defined in the XLIFF
-format; the domain should be named after the bundle name (``bundle.hello``).
+format; the :ref:`translation domain <using-message-domains>` should be named
+after the bundle name (``bundle.hello``).
 
 A bundle must not override existing messages from another bundle.
 
@@ -369,27 +364,17 @@ The end user can provide values in any configuration file:
         // app/config/config.php
         $container->setParameter('acme_hello.email.from', 'fabien@example.com');
 
-    .. code-block:: ini
-
-        ; app/config/config.ini
-        [parameters]
-        acme_hello.email.from = fabien@example.com
-
 Retrieve the configuration parameters in your code from the container::
 
     $container->getParameter('acme_hello.email.from');
 
 Even if this mechanism is simple enough, you are highly encouraged to use the
-semantic configuration described in the cookbook.
+:doc:`semantic bundle configuration </cookbook/bundles/extension>` instead.
 
 .. note::
 
     If you are defining services, they should also be prefixed with the bundle
     alias.
 
-Learn more from the Cookbook
-----------------------------
-
-* :doc:`/cookbook/bundles/extension`
-
-.. _standards: http://www.php-fig.org/psr/psr-4/
+.. _`standards`: http://www.php-fig.org/psr/psr-0/
+.. _`phpDocumentor`: http://www.phpdoc.org/
diff --git a/cookbook/bundles/configuration.rst b/cookbook/bundles/configuration.rst
@@ -6,13 +6,13 @@ How to Create Friendly Configuration for a Bundle
 =================================================
 
 If you open your application configuration file (usually ``app/config/config.yml``),
-you'll see a number of different configuration "namespaces", such as ``framework``,
+you'll see a number of different configuration sections, such as ``framework``,
 ``twig`` and ``doctrine``. Each of these configures a specific bundle, allowing
-you to configure things at a high level and then let the bundle make all the
+you to define options at a high level and then let the bundle make all the
 low-level, complex changes based on your settings.
 
-For example, the following tells the FrameworkBundle to enable the form
-integration, which involves the definition of quite a few services as well
+For example, the following configuration tells the FrameworkBundle to enable the
+form integration, which involves the definition of quite a few services as well
 as integration of other related components:
 
 .. configuration-block::

diff --git a/cookbook/bundles/extension.rst b/cookbook/bundles/extension.rst
@@ -6,7 +6,7 @@ How to Load Service Configuration inside a Bundle
 =================================================
 
 In Symfony, you'll find yourself using many services. These services can be
-registered in the `app/config` directory of your application. But when you
+registered in the ``app/config/`` directory of your application. But when you
 want to decouple the bundle for use in other projects, you want to include the
 service configuration in the bundle itself. This article will teach you how to
 do that.
@@ -15,7 +15,7 @@ Creating an Extension Class
 ---------------------------
 
 In order to load service configuration, you have to create a Dependency
-Injection Extension for your bundle. This class has some conventions in order
+Injection (DI) Extension for your bundle. This class has some conventions in order
 to be detected automatically. But you'll later see how you can change it to
 your own preferences. By default, the Extension has to comply with the
 following conventions:

diff --git a/cookbook/bundles/inheritance.rst b/cookbook/bundles/inheritance.rst
@@ -12,16 +12,16 @@ things like controllers, templates, and other files in a bundle's
 
 For example, suppose that you're installing the `FOSUserBundle`_, but you
 want to override its base ``layout.html.twig`` template, as well as one of
-its controllers. Suppose also that you have your own AcmeUserBundle
-where you want the overridden files to live. Start by registering the FOSUserBundle
-as the "parent" of your bundle::
+its controllers. Suppose also that you have your own UserBundle where you want
+the overridden files to live. Start by registering the FOSUserBundle as the
+"parent" of your bundle::
 
-    // src/Acme/UserBundle/AcmeUserBundle.php
-    namespace Acme\UserBundle;
+    // src/UserBundle/UserBundle.php
+    namespace UserBundle;
 
     use Symfony\Component\HttpKernel\Bundle\Bundle;
 
-    class AcmeUserBundle extends Bundle
+    class UserBundle extends Bundle
     {
         public function getParent()
         {
@@ -45,8 +45,8 @@ Suppose you want to add some functionality to the ``registerAction`` of a
 just create your own ``RegistrationController.php`` file, override the bundle's
 original method, and change its functionality::
 
-    // src/Acme/UserBundle/Controller/RegistrationController.php
-    namespace Acme\UserBundle\Controller;
+    // src/UserBundle/Controller/RegistrationController.php
+    namespace UserBundle\Controller;
 
     use FOS\UserBundle\Controller\RegistrationController as BaseController;
 
@@ -82,17 +82,17 @@ location as your parent bundle.
 For example, it's very common to need to override the FOSUserBundle's
 ``layout.html.twig`` template so that it uses your application's base layout.
 Since the file lives at ``Resources/views/layout.html.twig`` in the FOSUserBundle,
-you can create your own file in the same location of AcmeUserBundle.
-Symfony will ignore the file that lives inside the FOSUserBundle entirely,
-and use your file instead.
+you can create your own file in the same location of UserBundle. Symfony will
+ignore the file that lives inside the FOSUserBundle entirely, and use your file
+instead.
 
 The same goes for routing files and some other resources.
 
 .. note::
 
     The overriding of resources only works when you refer to resources with
     the ``@FOSUserBundle/Resources/config/routing/security.xml`` method.
-    If you refer to resources without using the @BundleName shortcut, they
+    If you refer to resources without using the ``@BundleName`` shortcut, they
     can't be overridden in this way.
 
 .. caution::

diff --git a/cookbook/bundles/installation.rst b/cookbook/bundles/installation.rst
@@ -15,16 +15,16 @@ A) Add Composer Dependencies
 ----------------------------
 
 Dependencies are managed with Composer, so if Composer is new to you, learn
-some basics in `their documentation`_. This has 2 steps:
+some basics in `their documentation`_. This involves two steps:
 
 1) Find out the Name of the Bundle on Packagist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The README for a bundle (e.g. `FOSUserBundle`_) usually tells you its name
 (e.g. ``friendsofsymfony/user-bundle``). If it doesn't, you can search for
-the library on the `Packagist.org`_ site.
+the bundle on the `Packagist.org`_ site.
 
-.. note::
+.. tip::
 
     Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
     archive of Symfony Bundles.
@@ -39,9 +39,12 @@ Now that you know the package name, you can install it via Composer:
     $ composer require friendsofsymfony/user-bundle
 
 This will choose the best version for your project, add it to ``composer.json``
-and download the library into the ``vendor/`` directory. If you need a specific
-version, add a ``:`` and the version right after the library name (see
-`composer require`_).
+and download its code into the ``vendor/`` directory. If you need a specific
+version, include it as the second argument of the `composer require`_ command:
+
+.. code-block:: bash
+
+    $ composer require friendsofsymfony/user-bundle "~2.0@dev"
 
 B) Enable the Bundle
 --------------------
@@ -68,22 +71,46 @@ The only thing you need to do now is register the bundle in ``AppKernel``::
         }
     }
 
+By default, Symfony bundles are registered in all the application
+:doc:`execution environments <cookbook/configuration/environments>`. If the bundle
+is meant to be used only in the development or test environments, register it in
+the section below::
+
+    // app/AppKernel.php
+
+    // ...
+    class AppKernel extends Kernel
+    {
+        // ...
+
+        public function registerBundles()
+        {
+            $bundles = array(
+                // ...,
+            );
+
+            if (in_array($this->getEnvironment(), array('dev', 'test'))) {
+                $bundles[] = new FOS\UserBundle\FOSUserBundle();
+            }
+
+            // ...
+        }
+    }
+
 C) Configure the Bundle
 -----------------------
 
 It's pretty common for a bundle to need some additional setup or configuration
 in ``app/config/config.yml``. The bundle's documentation will tell you about
-the configuration, but you can also get a reference of the bundle's config
-via the ``config:dump-reference`` command.
-
-For instance, in order to look the reference of the ``assetic`` config you
-can use this:
+the configuration, but you can also get a reference of the bundle's configuration
+via the ``config:dump-reference`` command:
 
 .. code-block:: bash
 
     $ app/console config:dump-reference AsseticBundle
 
-or this:
+Instead of the full bundle name, you can also pass the short name used as the root
+of the bundle's configuration:
 
 .. code-block:: bash