Merge branch '2.8'

* 2.8:
  Remove horizontal scrollbar
  Fixed typo.
  Minor rewording
  Fixed a minor grammar issue
  Minor rewording
  Fixed some typos
  Improved the explanation about the "secret" configuration parameter

Author: weaverryan

book/installation.rst

@@ -305,7 +305,7 @@ several minutes to complete.
 .. tip::
 
     Symfony provides a command to check whether your project's dependencies
-    contain any know security vulnerability:
+    contain any known security vulnerability:
 
     .. code-block:: bash
 

cookbook/console/commands_as_services.rst

@@ -38,11 +38,13 @@ with ``console.command``:
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+            http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="acme_hello.command.my_command"
                     class="Acme\HelloBundle\Command\MyCommand">
+
                     <tag name="console.command" />
                 </service>
             </services>
@@ -52,7 +54,10 @@ with ``console.command``:
 
         // app/config/config.php
         $container
-            ->register('acme_hello.command.my_command', 'Acme\HelloBundle\Command\MyCommand')
+            ->register(
+                'acme_hello.command.my_command',
+                'Acme\HelloBundle\Command\MyCommand'
+            )
             ->addTag('console.command')
         ;
 
@@ -63,7 +68,7 @@ Imagine you want to provide a default value for the ``name`` option. You could
 pass one of the following as the 5th argument of ``addOption()``:
 
 * a hardcoded string;
-* a container parameter (e.g. something from parameters.yml);
+* a container parameter (e.g. something from ``parameters.yml``);
 * a value computed by a service (e.g. a repository).
 
 By extending ``ContainerAwareCommand``, only the first is possible, because you
@@ -98,7 +103,13 @@ have some ``NameRepository`` service that you'll use to get your default value::
             $this
                 ->setName('demo:greet')
                 ->setDescription('Greet someone')
-                ->addOption('name', '-n', InputOption::VALUE_REQUIRED, 'Who do you want to greet?', $defaultName)
+                ->addOption(
+                    'name',
+                    '-n',
+                    InputOption::VALUE_REQUIRED,
+                    'Who do you want to greet?',
+                    $defaultName
+                )
             ;
         }
 

reference/configuration/framework.rst

@@ -69,10 +69,24 @@ secret
 
 **type**: ``string`` **required**
 
-This is a string that should be unique to your application. In practice,
-it's used for generating the CSRF tokens, but it could be used in any other
-context where having a unique string is useful. It becomes the service container
-parameter named ``kernel.secret``.
+This is a string that should be unique to your application and it's commonly used
+to add more entropy to security related operations. Its value should be a series of
+characters, numbers and symbols chosen randomly and the recommended length is
+around 32 characters.
+
+In practice, Symfony uses this value for generating the :ref:`CSRF tokens <forms-csrf>`,
+for encrypting the cookies used in the :doc:`remember me functionality </cookbook/security/remember_me>`
+and for creating signed URIs when using :ref:`ESI (Edge Side Includes) <edge-side-includes>` .
+
+This option becomes the service container parameter named ``kernel.secret``,
+which you can use whenever the application needs an immutable random string
+to add more entropy.
+
+As with any other security-related parameter, it is a good practice to change this
+value from time to time. However, keep in mind that changing this value will
+invalidate all signed URIs and Remember Me cookies. That's why, after changing
+this value, you should regenerate the application cache and log out all the
+application users.
 
 .. _configuration-framework-http_method_override: