feature #5401 Added some more docs about the remember me feature (WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Added some more docs about the remember me feature

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

Commits
-------

ce6b808 Added some more docs about the remember me feature

Author: weaverryan

cookbook/security/remember_me.rst

@@ -16,11 +16,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
 
         # app/config/security.yml
         firewalls:
-            main:
+            default:
+                # ...
                 remember_me:
                     key:      "%secret%"
                     lifetime: 604800 # 1 week in seconds
                     path:     /
+                    # by default, the feature is enabled by checking a
+                    # checkbox in the login form (see below), uncomment the
+                    # below lines to always enable it.
+                    #always_remember_me: true
 
     .. code-block:: xml
 
@@ -33,12 +38,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
-                <firewall>
-                    <!-- lifetime: 604800 seconds = 1 week -->
+                <firewall name="default">
+                    <!-- ... -->
+
+                    <!-- by default, the feature is enabled by checking a checkbox
+                         in the login form (see below), add always-remember-me="true"
+                         to always enable it. -->
                     <remember-me
-                        key="%secret%"
-                        lifetime="604800"
-                        path="/"
+                        key      = "%secret%"
+                        lifetime = "604800" <!-- 1 week in seconds -->
+                        path     = "/"
                     />
                 </firewall>
             </config>
@@ -49,11 +58,16 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
         // app/config/security.php
         $container->loadFromExtension('security', array(
             'firewalls' => array(
-                'main' => array(
+                'default' => array(
+                    // ...
                     'remember_me' => array(
                         'key'      => '%secret%',
                         'lifetime' => 604800, // 1 week in seconds
                         'path'     => '/',
+                        // by default, the feature is enabled by checking a
+                        // checkbox in the login form (see below), uncomment
+                        // the below lines to always enable it.
+                        //'always_remember_me' => true,
                     ),
                 ),
             ),
@@ -103,21 +117,30 @@ The ``remember_me`` firewall defines the following configuration options:
     "Remember Me" feature is always enabled, regardless of the desire of the
     end user.
 
+``token_provider`` (default value: ``null``)
+    Defines the service id of a token provider to use. By default, tokens are
+    stored in a cookie. For example, you might want to store the token in a
+    database, to not have a (hashed) version of the password in a cookie. The
+    DoctrineBridge comes with a
+    ``Symfony\Bridge\Doctrine\Security\RememberMe\DoctrineTokenProvider`` that
+    you can use.
+
 Forcing the User to Opt-Out of the Remember Me Feature
 ------------------------------------------------------
 
 It's a good idea to provide the user with the option to use or not use the
 remember me functionality, as it will not always be appropriate. The usual
 way of doing this is to add a checkbox to the login form. By giving the checkbox
-the name ``_remember_me``, the cookie will automatically be set when the checkbox
-is checked and the user successfully logs in. So, your specific login form
-might ultimately look like this:
+the name ``_remember_me`` (or the name you configured using ``remember_me_parameter``),
+the cookie will automatically be set when the checkbox is checked and the user
+successfully logs in. So, your specific login form might ultimately look like
+this:
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
-        {# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #}
+        {# app/Resources/views/security/login.html.twig #}
         {% if error %}
             <div>{{ error.message }}</div>
         {% endif %}
@@ -137,7 +160,7 @@ might ultimately look like this:
 
     .. code-block:: html+php
 
-        <!-- src/Acme/SecurityBundle/Resources/views/Security/login.html.php -->
+        <!-- app/Resources/views/security/login.html.php -->
         <?php if ($error): ?>
             <div><?php echo $error->getMessage() ?></div>
         <?php endif ?>
@@ -159,7 +182,7 @@ might ultimately look like this:
 The user will then automatically be logged in on subsequent visits while
 the cookie remains valid.
 
-Forcing the User to Re-authenticate before Accessing certain Resources
+Forcing the User to Re-Authenticate before Accessing certain Resources
 ----------------------------------------------------------------------
 
 When the user returns to your site, they are authenticated automatically based