feature #4723 [Cookbook][Security] document the new AuthenticationUti…

…ls (xabbuh)

This PR was merged into the 2.6 branch.

Discussion
----------

[Cookbook][Security] document the new AuthenticationUtils

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#11324)
| Applies to    | 2.6+
| Fixed tickets | #3996

Commits
-------

dd7c1dd document the new AuthenticationUtils

cookbook/security/form_login_setup.rst

@@ -166,27 +166,15 @@ form::
     // src/AppBundle/Controller/SecurityController.php
     // ...
 
-    // ADD THIS use STATEMENT above your class
-    use Symfony\Component\Security\Core\Security;
-
     public function loginAction(Request $request)
     {
-        $session = $request->getSession();
+        $authenticationUtils = $this->get('security.authentication_utils');
 
         // get the login error if there is one
-        if ($request->attributes->has(Security::AUTHENTICATION_ERROR)) {
-            $error = $request->attributes->get(
-                Security::AUTHENTICATION_ERROR
-            );
-        } elseif (null !== $session && $session->has(Security::AUTHENTICATION_ERROR)) {
-            $error = $session->get(Security::AUTHENTICATION_ERROR);
-            $session->remove(Security::AUTHENTICATION_ERROR);
-        } else {
-            $error = null;
-        }
+        $error = $authenticationUtils->getLastAuthenticationError();
 
         // last username entered by the user
-        $lastUsername = (null === $session) ? '' : $session->get(Security::LAST_USERNAME);
+        $lastUsername = $authenticationUtils->getLastUsername();
 
         return $this->render(
             'security/login.html.twig',
@@ -198,6 +186,11 @@ form::
         );
     }
 
+.. versionadded:: 2.6
+    The ``security.authentication_utils`` service and the
+    :class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationUtils`
+    class were introduced in Symfony 2.6.
+
 Don't let this controller confuse you. As you'll see in a moment, when the
 user submits the form, the security system automatically handles the form
 submission for you. If the user had submitted an invalid username or password,