minor #5098 Reviewed Configuration cookbook articles (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Reviewed Configuration cookbook articles

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | -

Commits
-------

aedaccd Added a note against using the Apache Router
2feb801 Implemented all the changes suggested by reviewers
9f49497 Reviewed Configuration cookbook articles

Author: weaverryan

cookbook/configuration/apache_router.rst

@@ -4,8 +4,18 @@
 How to Use the Apache Router
 ============================
 
-Symfony, while fast out of the box, also provides various ways to increase that speed with a little bit of tweaking.
-One of these ways is by letting Apache handle routes directly, rather than using Symfony for this task.
+.. caution::
+
+    **Using the Apache Router is no longer considered a good practice**.
+    The small increase obtained in the application routing performance is not
+    worth the hassle of continuously updating the routes configuration.
+
+    The Apache Router will be removed in Symfony 3 and it's highly recommended
+    to not use it in your applications.
+
+Symfony, while fast out of the box, also provides various ways to increase that
+speed with a little bit of tweaking. One of these ways is by letting Apache
+handle routes directly, rather than using Symfony for this task.
 
 Change Router Configuration Parameters
 --------------------------------------
@@ -61,20 +71,20 @@ To test that it's working, create a very basic route for the AppBundle:
         # app/config/routing.yml
         hello:
             path: /hello/{name}
-            defaults: { _controller: AppBundle:Demo:hello }
+            defaults: { _controller: AppBundle:Greet:hello }
 
     .. code-block:: xml
 
         <!-- app/config/routing.xml -->
         <route id="hello" path="/hello/{name}">
-            <default key="_controller">AppBundle:Demo:hello</default>
+            <default key="_controller">AppBundle:Greet:hello</default>
         </route>
 
     .. code-block:: php
 
         // app/config/routing.php
         $collection->add('hello', new Route('/hello/{name}', array(
-            '_controller' => 'AppBundle:Demo:hello',
+            '_controller' => 'AppBundle:Greet:hello',
         )));
 
 Now generate the mod_rewrite rules:
@@ -93,7 +103,7 @@ Which should roughly output the following:
 
     # hello
     RewriteCond %{REQUEST_URI} ^/hello/([^/]+?)$
-    RewriteRule .* app.php [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AppBundle\:Demo\:hello]
+    RewriteRule .* app.php [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AppBundle\:Default\:hello]
 
 You can now rewrite ``web/.htaccess`` to use the new rules, so with this example
 it should look like this:
@@ -109,12 +119,13 @@ it should look like this:
 
         # hello
         RewriteCond %{REQUEST_URI} ^/hello/([^/]+?)$
-        RewriteRule .* app.php [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AppBundle\:Demo\:hello]
+        RewriteRule .* app.php [QSA,L,E=_ROUTING__route:hello,E=_ROUTING_name:%1,E=_ROUTING__controller:AppBundle\:Default\:hello]
     </IfModule>
 
 .. note::
 
-   The procedure above should be done each time you add/change a route if you want to take full advantage of this setup.
+   The procedure above should be done each time you add/change a route if you
+   want to take full advantage of this setup.
 
 That's it!
 You're now all set to use Apache routes.

cookbook/configuration/environments.rst

@@ -20,7 +20,7 @@ Different Environments, different Configuration Files
 -----------------------------------------------------
 
 A typical Symfony application begins with three environments: ``dev``,
-``prod``, and ``test``. As discussed, each "environment" simply represents
+``prod``, and ``test``. As mentioned, each environment simply represents
 a way to execute the same codebase with different configuration. It should
 be no surprise then that each environment loads its own individual configuration
 file. If you're using the YAML configuration format, the following files
@@ -55,8 +55,8 @@ multiple environments in an elegant, powerful and transparent way.
 
 Of course, in reality, each environment differs only somewhat from others.
 Generally, all environments will share a large base of common configuration.
-Opening the "dev" configuration file, you can see how this is accomplished
-easily and transparently:
+Opening the ``config_dev.yml`` configuration file, you can see how this is
+accomplished easily and transparently:
 
 .. configuration-block::
 
@@ -86,7 +86,8 @@ simply first imports from a central configuration file (``config.yml``).
 The remainder of the file can then deviate from the default configuration
 by overriding individual parameters. For example, by default, the ``web_profiler``
 toolbar is disabled. However, in the ``dev`` environment, the toolbar is
-activated by modifying the default value in the ``dev`` configuration file:
+activated by modifying the value of the ``toolbar`` option in the ``config_dev.yml``
+configuration file:
 
 .. configuration-block::
 
@@ -151,9 +152,9 @@ used by each is explicitly set::
 
     // ...
 
-As you can see, the ``prod`` key specifies that this application will run
-in the ``prod`` environment. A Symfony application can be executed in any
-environment by using this code and changing the environment string.
+The ``prod`` key specifies that this application will run in the ``prod``
+environment. A Symfony application can be executed in any environment by using
+this code and changing the environment string.
 
 .. note::
 
@@ -325,9 +326,7 @@ The new environment is now accessible via::
     certain environments, for debugging purposes, may give too much information
     about the application or underlying infrastructure. To be sure these environments
     aren't accessible, the front controller is usually protected from external
-    IP addresses via the following code at the top of the controller:
-
-    .. code-block:: php
+    IP addresses via the following code at the top of the controller::
 
         if (!in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', '::1'))) {
             die('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
@@ -361,17 +360,20 @@ the directory of the environment you're using (most commonly ``dev`` while
 developing and debugging). While it can vary, the ``app/cache/dev`` directory
 includes the following:
 
-* ``appDevDebugProjectContainer.php`` - the cached "service container" that
-  represents the cached application configuration;
+``appDevDebugProjectContainer.php``
+    The cached "service container" that represents the cached application
+    configuration.
 
-* ``appDevUrlGenerator.php`` - the PHP class generated from the routing
-  configuration and used when generating URLs;
+``appDevUrlGenerator.php``
+    The PHP class generated from the routing configuration and used when
+    generating URLs.
 
-* ``appDevUrlMatcher.php`` - the PHP class used for route matching - look
-  here to see the compiled regular expression logic used to match incoming
-  URLs to different routes;
+``appDevUrlMatcher.php``
+    The PHP class used for route matching - look here to see the compiled regular
+    expression logic used to match incoming URLs to different routes.
 
-* ``twig/`` - this directory contains all the cached Twig templates.
+``twig/``
+    This directory contains all the cached Twig templates.
 
 .. note::
 

cookbook/configuration/front_controllers_and_kernel.rst

@@ -94,12 +94,10 @@ There are two methods declared in the
 left unimplemented in :class:`Symfony\\Component\\HttpKernel\\Kernel`
 and thus serve as `template methods`_:
 
-* :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerBundles`,
-  which must return an array of all bundles needed to run the
-  application;
-
-* :method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`,
-  which loads the application configuration.
+:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerBundles`
+    It must return an array of all bundles needed to run the application.
+:method:`Symfony\\Component\\HttpKernel\\KernelInterface::registerContainerConfiguration`
+    It loads the application configuration.
 
 To fill these (small) blanks, your application needs to subclass the
 Kernel and implement these methods. The resulting class is conventionally
@@ -124,8 +122,7 @@ controller to make use of the new kernel.
     it might therefore make sense to add additional sub-directories,
     for example ``app/admin/AdminKernel.php`` and
     ``app/api/ApiKernel.php``. All that matters is that your front
-    controller is able to create an instance of the appropriate
-    kernel.
+    controller is able to create an instance of the appropriate kernel.
 
 Having different ``AppKernels`` might be useful to enable different front
 controllers (on potentially different servers) to run parts of your application

cookbook/configuration/override_dir_structure.rst

@@ -29,7 +29,7 @@ directory structure is:
 Override the ``cache`` Directory
 --------------------------------
 
-You can override the cache directory by overriding the ``getCacheDir`` method
+You can change the default cache directory by overriding the ``getCacheDir`` method
 in the ``AppKernel`` class of you application::
 
     // app/AppKernel.php
@@ -53,16 +53,16 @@ the location of the cache directory to ``app/{environment}/cache``.
 
     You should keep the ``cache`` directory different for each environment,
     otherwise some unexpected behavior may happen. Each environment generates
-    its own cached config files, and so each needs its own directory to store
-    those cache files.
+    its own cached configuration files, and so each needs its own directory to
+    store those cache files.
 
 .. _override-logs-dir:
 
 Override the ``logs`` Directory
 -------------------------------
 
 Overriding the ``logs`` directory is the same as overriding the ``cache``
-directory, the only difference is that you need to override the ``getLogDir``
+directory. The only difference is that you need to override the ``getLogDir``
 method::
 
     // app/AppKernel.php
@@ -80,14 +80,16 @@ method::
 
 Here you have changed the location of the directory to ``app/{environment}/logs``.
 
+.. _override-web-dir:
+
 Override the ``web`` Directory
 ------------------------------
 
 If you need to rename or move your ``web`` directory, the only thing you
 need to guarantee is that the path to the ``app`` directory is still correct
 in your ``app.php`` and ``app_dev.php`` front controllers. If you simply
 renamed the directory, you're fine. But if you moved it in some way, you
-may need to modify the paths inside these files::
+may need to modify these paths inside those files::
 
     require_once __DIR__.'/../Symfony/app/bootstrap.php.cache';
     require_once __DIR__.'/../Symfony/app/AppKernel.php';
@@ -116,8 +118,8 @@ the ``extra.symfony-web-dir`` option in the ``composer.json`` file:
 
 .. note::
 
-    If you use the AsseticBundle you need to configure this, so it can use
-    the correct ``web`` directory:
+    If you use the AsseticBundle, you need to configure the ``read_from`` option
+    to point to the correct ``web`` directory:
 
     .. configuration-block::
 
@@ -147,8 +149,8 @@ the ``extra.symfony-web-dir`` option in the ``composer.json`` file:
                 'read_from' => '%kernel.root_dir%/../../public_html',
             ));
 
-    Now you just need to clear the cache and dump the assets again and your application should
-    work:
+    Now you just need to clear the cache and dump the assets again and your
+    application should work:
 
     .. code-block:: bash
 
@@ -159,10 +161,7 @@ Override the ``vendor`` Directory
 ---------------------------------
 
 To override the ``vendor`` directory, you need to introduce changes in the
-following files:
-
-* ``app/autoload.php``
-* ``composer.json``
+``app/autoload.php`` and ``composer.json`` files.
 
 The change in the ``composer.json`` will look like this:
 
@@ -177,8 +176,8 @@ The change in the ``composer.json`` will look like this:
         ...
     }
 
-In ``app/autoload.php``, you need to modify the path leading to the ``vendor/autoload.php``
-file::
+In ``app/autoload.php``, you need to modify the path leading to the
+``vendor/autoload.php`` file::
 
     // app/autoload.php
     // ...
@@ -187,5 +186,5 @@ file::
 .. tip::
 
     This modification can be of interest if you are working in a virtual environment
-    and cannot use NFS - for example, if you're running a Symfony app using
+    and cannot use NFS - for example, if you're running a Symfony application using
     Vagrant/VirtualBox in a guest operating system.

cookbook/configuration/pdo_session_storage.rst

@@ -4,15 +4,14 @@
 How to Use PdoSessionHandler to Store Sessions in the Database
 ==============================================================
 
-The default Symfony session storage writes the session information to
-file(s). Most medium to large websites use a database to store the session
-values instead of files, because databases are easier to use and scale in a
+The default Symfony session storage writes the session information to files.
+Most medium to large websites use a database to store the session values
+instead of files, because databases are easier to use and scale in a
 multi-webserver environment.
 
 Symfony has a built-in solution for database session storage called
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\PdoSessionHandler`.
-To use it, you just need to change some parameters in ``config.yml`` (or the
-configuration format of your choice):
+To use it, you just need to change some parameters in the main configuration file:
 
 .. versionadded:: 2.1
     In Symfony 2.1 the class and namespace are slightly modified. You can now
@@ -120,10 +119,19 @@ configuration format of your choice):
         ));
         $container->setDefinition('session.handler.pdo', $storageDefinition);
 
-* ``db_table``: The name of the session table in your database
-* ``db_id_col``: The name of the id column in your session table (VARCHAR(255) or larger)
-* ``db_data_col``: The name of the value column in your session table (TEXT or CLOB)
-* ``db_time_col``: The name of the time column in your session table (INTEGER)
+These are parameters that you must configure:
+
+``db_table``
+    The name of the session table in your database.
+
+``db_id_col``
+    The name of the id column in your session table (``VARCHAR(255)`` or larger).
+
+``db_data_col``
+    The name of the value column in your session table (``TEXT`` or ``CLOB``).
+
+``db_time_col``:
+    The name of the time column in your session table (``INTEGER``).
 
 Sharing your Database Connection Information
 --------------------------------------------

cookbook/configuration/using_parameters_in_dic.rst

@@ -11,17 +11,17 @@ There are special cases such as when you want, for instance, to use the
 debug mode. For this case there is more work to do in order
 to make the system understand the parameter value. By default
 your parameter ``%kernel.debug%`` will be treated as a
-simple string. Consider this example with the AcmeDemoBundle::
+simple string. Consider the following example::
 
-    // Inside Configuration class
+    // inside Configuration class
     $rootNode
         ->children()
             ->booleanNode('logging')->defaultValue('%kernel.debug%')->end()
             // ...
         ->end()
     ;
 
-    // Inside the Extension class
+    // inside the Extension class
     $config = $this->processConfiguration($configuration, $configs);
     var_dump($config['logging']);
 
@@ -111,7 +111,7 @@ be injected with this parameter via the extension as follows::
         public function getConfigTreeBuilder()
         {
             $treeBuilder = new TreeBuilder();
-            $rootNode = $treeBuilder->root('acme_demo');
+            $rootNode = $treeBuilder->root('my_bundle');
 
             $rootNode
                 ->children()
@@ -127,14 +127,14 @@ be injected with this parameter via the extension as follows::
 
 And set it in the constructor of ``Configuration`` via the ``Extension`` class::
 
-    namespace Acme\DemoBundle\DependencyInjection;
+    namespace AppBundle\DependencyInjection;
 
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
     use Symfony\Component\HttpKernel\DependencyInjection\Extension;
     use Symfony\Component\Config\FileLocator;
 
-    class AcmeDemoExtension extends Extension
+    class AppExtension extends Extension
     {
         // ...
 
@@ -147,7 +147,7 @@ And set it in the constructor of ``Configuration`` via the ``Extension`` class::
 .. sidebar:: Setting the Default in the Extension
 
     There are some instances of ``%kernel.debug%`` usage within a ``Configurator``
-    class in TwigBundle and AsseticBundle, however this is because the default
+    class in TwigBundle and AsseticBundle. However this is because the default
     parameter value is set by the Extension class. For example in AsseticBundle,
     you can find::