Merge branch '2.8' into 3.1

* 2.8: (37 commits)
  fix a typo
  [symfony#7115] fix headlines
  Better explain the most common problems when testing emails
  Clarify the mappings that require no method prefix.
  Make some long lines shorter to fit our soft limit of 80 chars per line
  Microsoft Azure update step by step article and screenshots for the new Microsoft Azure Portal
  Minor rewords in the text and the code example
  Update questionhelper.rst
  Add docs about console question answer normalizing.
  [symfony#7105] add XML and PHP service config examples
  Minor rewordings
  When talking about generic responses, don't spell it as Response (which is a Symfony class)
  xabbuh review
  fix typo
  fix yml marker to yaml
  add documentation about access denied handler
  Update outdated link to AWS ELB security groups
  Added missing comma
  Reworded the caution about open redirects
  Warn user about open redirects
  ...

Author: xabbuh

_images/deployment/azure-website/step-01.png

@@ -129,7 +129,7 @@ Using Expressions for Complex Security Restrictions
 
 If your security logic is a little bit more complex, you can use an :doc:`expression </components/expression_language>`
 inside ``@Security``. In the following example, a user can only access the
-controller if their email matches the value returned by the ``getAuthorEmail``
+controller if their email matches the value returned by the ``getAuthorEmail()``
 method on the ``Post`` object:
 
 .. code-block:: php
@@ -258,7 +258,7 @@ of magnitude easier than :doc:`ACLs </security/acl>` and will give
 you the flexibility you need in almost all cases.
 
 First, create a voter class. The following example shows a voter that implements
-the same ``getAuthorEmail`` logic you used above:
+the same ``getAuthorEmail()`` logic you used above:
 
 .. code-block:: php
 

_images/deployment/azure-website/step-02.png

@@ -90,7 +90,7 @@ but it is more common if you put these definitions in a configuration file
 the extension!
 
 For instance, assume you have a file called ``services.xml`` in the
-``Resources/config`` directory of your bundle, your load method looks like::
+``Resources/config`` directory of your bundle, your ``load()`` method looks like::
 
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
     use Symfony\Component\Config\FileLocator;

_images/deployment/azure-website/step-03.png

@@ -10,11 +10,12 @@ in one of your own bundles. Symfony gives you a very convenient way to override
 things like controllers, templates, and other files in a bundle's
 ``Resources/`` directory.
 
-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 UserBundle where you want
-the overridden files to live. Start by registering the FOSUserBundle as the
-"parent" of your bundle::
+For example, suppose that you have installed `FOSUserBundle`_, but you want to
+override its base ``layout.html.twig`` template, as well as one of its
+controllers.
+
+First, create a new bundle called UserBundle and enable it in your application.
+Then, register the third-party FOSUserBundle as the "parent" of your bundle::
 
     // src/UserBundle/UserBundle.php
     namespace UserBundle;
@@ -40,7 +41,7 @@ simply by creating a file with the same name.
 Overriding Controllers
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose you want to add some functionality to the ``registerAction`` of a
+Suppose you want to add some functionality to the ``registerAction()`` of a
 ``RegistrationController`` that lives inside FOSUserBundle. To do so,
 just create your own ``RegistrationController.php`` file, override the bundle's
 original method, and change its functionality::

_images/deployment/azure-website/step-04.png

@@ -1,5 +1,9 @@
 .. index::
     single: CHANGELOG
+    
+.. !! CAUTION !!
+   This file is automatically generated. Do not add new changelog
+   items when preparing a pull request.
 
 The Documentation Changelog
 ===========================
@@ -308,7 +312,7 @@ Minor Documentation Changes
 * `#30 <https://github.com/symfony/symfony-docs/pull/30>`_ Moved the rest of the book chapters (javiereguiluz)
 * `#24 <https://github.com/symfony/symfony-docs/pull/24>`_ Moved book chapters out of the book (javiereguiluz)
 * `#20 <https://github.com/symfony/symfony-docs/pull/20>`_ Creating the Controller topic (xabbuh)
-* `#6747 <https://github.com/symfony/symfony-docs/pull/6747>`_ Correcting reference to ``isSuccessful`` method for Process (aedmonds)
+* `#6747 <https://github.com/symfony/symfony-docs/pull/6747>`_ Correcting reference to ``isSuccessful()`` method for Process (aedmonds)
 * `#6600 <https://github.com/symfony/symfony-docs/pull/6600>`_ Removing some extra details from #6444 (weaverryan)
 * `#6715 <https://github.com/symfony/symfony-docs/pull/6715>`_ [Book] Remove DI extension info and link the cookbook article instead (WouterJ)
 * `#6745 <https://github.com/symfony/symfony-docs/pull/6745>`_ Branch fix (Talita Kocjan Zager, weaverryan)

_images/deployment/azure-website/step-05.png

@@ -471,7 +471,7 @@ methods::
                 ->defaultFalse()
     ;
 
-The ``canBeDisabled`` method looks about the same except that the section
+The ``canBeDisabled()`` method looks about the same except that the section
 would be enabled by default.
 
 Merging Options
@@ -651,7 +651,7 @@ a second argument::
         ->end()
     ;
 
-As well as fixing this, ``fixXmlConfig`` ensures that single XML elements
+As well as fixing this, ``fixXmlConfig()`` ensures that single XML elements
 are still turned into an array. So you may have:
 
 .. code-block:: xml
@@ -667,7 +667,7 @@ and sometimes only:
 
 By default ``connection`` would be an array in the first case and a string
 in the second making it difficult to validate. You can ensure it is always
-an array with ``fixXmlConfig``.
+an array with ``fixXmlConfig()``.
 
 You can further control the normalization process if you need to. For example,
 you may want to allow a string to be set and used as a particular key or

_images/deployment/azure-website/step-06.png

@@ -6,7 +6,7 @@ Changing the Default Command
 
 The Console component will always run the ``ListCommand`` when no command name is
 passed. In order to change the default command you just need to pass the command
-name to the ``setDefaultCommand`` method::
+name to the ``setDefaultCommand()`` method::
 
     namespace Acme\Console\Command;
 

_images/deployment/azure-website/step-07.png

@@ -205,6 +205,38 @@ convenient for passwords::
     like in the example above. In this case, a ``RuntimeException``
     would be thrown.
 
+Normalizing the Answer
+----------------------
+
+Before validating the answer, you can "normalize" it to fix minor errors or
+tweak it as needed. For instance, in a previous example you asked for the bundle
+name. In case the user adds white spaces around the name by mistake, you can
+trim the name before validating it. To do so, configure a normalizer using the
+:method:`Symfony\\Component\\Console\\Question\\Question::setNormalizer`
+method::
+
+    use Symfony\Component\Console\Question\Question;
+
+    // ...
+    public function execute(InputInterface $input, OutputInterface $output)
+    {
+        // ...
+        $question = new Question('Please enter the name of the bundle', 'AppBundle');
+        $question->setNormalizer(function ($value) {
+            // $value can be null here
+            return $value ? trim($value) : '';
+        });
+
+        $name = $helper->ask($input, $output, $question);
+    }
+
+
+.. caution::
+
+    The normalizer is called first and the returned value is used as the input
+    of the validator. If the answer is invalid, don't throw exceptions in the
+    normalizer and let the validator handle those errors.
+
 Validating the Answer
 ---------------------
 
@@ -222,11 +254,12 @@ method::
         // ...
         $question = new Question('Please enter the name of the bundle', 'AcmeDemoBundle');
         $question->setValidator(function ($answer) {
-            if ('Bundle' !== substr($answer, -6)) {
+            if (!is_string($answer) || 'Bundle' !== substr($answer, -6)) {
                 throw new \RuntimeException(
                     'The name of the bundle should be suffixed with \'Bundle\''
                 );
             }
+
             return $answer;
         });
         $question->setMaxAttempts(2);

_images/deployment/azure-website/step-08.png

@@ -34,7 +34,7 @@ long and unwieldy expressions.
 
 Many developers -- particularly web developers -- are more comfortable
 using CSS selectors to find elements. As well as working in stylesheets,
-CSS selectors are used in JavaScript with the ``querySelectorAll`` function
+CSS selectors are used in JavaScript with the ``querySelectorAll()`` function
 and in popular JavaScript libraries such as jQuery, Prototype and MooTools.
 
 CSS selectors are less powerful than XPath, but far easier to write, read

_images/deployment/azure-website/step-09.png

@@ -44,16 +44,16 @@ and can be registered with the container with::
 
     $container->registerExtension($extension);
 
-The main work of the extension is done in the ``load`` method. In the ``load``
+The main work of the extension is done in the ``load()`` method. In the ``load()``
 method you can load configuration from one or more configuration files as
 well as manipulate the container definitions using the methods shown in
 :doc:`/service_container/definitions`.
 
-The ``load`` method is passed a fresh container to set up, which is then
+The ``load()`` method is passed a fresh container to set up, which is then
 merged afterwards into the container it is registered with. This allows
 you to have several extensions managing container definitions independently.
 The extensions do not add to the containers configuration when they are
-added but are processed when the container's ``compile`` method is called.
+added but are processed when the container's ``compile()`` method is called.
 
 A very simple extension may just load configuration files into the container::
 
@@ -85,7 +85,7 @@ sections of config files loaded directly into the container as being for
 a particular extension. These sections on the config will not be processed
 directly by the container but by the relevant Extension.
 
-The Extension must specify a ``getAlias`` method to implement the interface::
+The Extension must specify a ``getAlias()`` method to implement the interface::
 
     // ...
 
@@ -100,7 +100,7 @@ The Extension must specify a ``getAlias`` method to implement the interface::
     }
 
 For YAML configuration files specifying the alias for the extension as a
-key will mean that those values are passed to the Extension's ``load`` method:
+key will mean that those values are passed to the Extension's ``load()`` method:
 
 .. code-block:: yaml
 
@@ -133,7 +133,7 @@ are loaded::
     or an exception will be thrown.
 
 The values from those sections of the config files are passed into the first
-argument of the ``load`` method of the extension::
+argument of the ``load()`` method of the extension::
 
     public function load(array $configs, ContainerBuilder $container)
     {
@@ -190,7 +190,7 @@ the XML configuration::
 
 .. note::
 
-    XSD validation is optional, returning ``false`` from the ``getXsdValidationBasePath``
+    XSD validation is optional, returning ``false`` from the ``getXsdValidationBasePath()``
     method will disable it.
 
 The XML version of the config would then look like this:

_images/deployment/azure-website/step-10.png

@@ -286,7 +286,7 @@ Links
 ~~~~~
 
 To find a link by name (or a clickable image by its ``alt`` attribute), use
-the ``selectLink`` method on an existing crawler. This returns a ``Crawler``
+the ``selectLink()`` method on an existing crawler. This returns a ``Crawler``
 instance with just the selected link(s). Calling ``link()`` gives you a special
 :class:`Symfony\\Component\\DomCrawler\\Link` object::
 

_images/deployment/azure-website/step-11.png

@@ -152,7 +152,7 @@ The ``addListener()`` method takes up to three arguments:
     A `PHP callable`_ is a PHP variable that can be used by the
     ``call_user_func()`` function and returns ``true`` when passed to the
     ``is_callable()`` function. It can be a ``\Closure`` instance, an object
-    implementing an ``__invoke`` method (which is what closures are in fact),
+    implementing an ``__invoke()`` method (which is what closures are in fact),
     a string representing a function or an array representing an object
     method or a class method.
 

_images/deployment/azure-website/step-12.png

@@ -35,4 +35,4 @@ Now, inject that into an ``ImmutableEventDispatcher``::
 You'll need to use this new dispatcher in your project.
 
 If you are trying to execute one of the methods which modifies the dispatcher
-(e.g. ``addListener``), a ``BadMethodCallException`` is thrown.
+(e.g. ``addListener()``), a ``BadMethodCallException`` is thrown.

_images/deployment/azure-website/step-13.png

@@ -51,7 +51,7 @@ second argument of the constructor.
 
 The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to
 acquire the lock. If the lock is acquired, the method returns ``true``,
-``false`` otherwise. If the ``lock`` method is called several times on the same
+``false`` otherwise. If the ``lock()`` method is called several times on the same
 instance it will always return ``true`` if the lock was acquired on the first
 call.
 

_images/deployment/azure-website/step-14.png

@@ -366,7 +366,7 @@ Creating a simple Form
     If you're using the Symfony Framework, then the form factory is available
     automatically as a service called ``form.factory``. Also, the default
     base controller class has a :method:`Symfony\\Bundle\\FrameworkBundle\\Controller::createFormBuilder`
-    method, which is a shortcut to fetch the form factory and call ``createBuilder``
+    method, which is a shortcut to fetch the form factory and call ``createBuilder()``
     on it.
 
 Creating a form is done via a :class:`Symfony\\Component\\Form\\FormBuilder`
@@ -419,8 +419,8 @@ is created from the form factory.
             }
         }
 
-As you can see, creating a form is like writing a recipe: you call ``add``
-for each new field you want to create. The first argument to ``add`` is the
+As you can see, creating a form is like writing a recipe: you call ``add()``
+for each new field you want to create. The first argument to ``add()`` is the
 name of your field, and the second is the fully qualified class name. The Form
 component comes with a lot of :doc:`built-in types </reference/forms/types>`.
 

_images/deployment/azure-website/step-15.png

@@ -11,7 +11,7 @@ The HttpFoundation Component
 
 In PHP, the request is represented by some global variables (``$_GET``,
 ``$_POST``, ``$_FILES``, ``$_COOKIE``, ``$_SESSION``, ...) and the response is
-generated by some functions (``echo``, ``header``, ``setcookie``, ...).
+generated by some functions (``echo``, ``header()``, ``setcookie()``, ...).
 
 The Symfony HttpFoundation component replaces these default PHP global
 variables and functions by an object-oriented layer.