Added the documentation for the success/failure handlers

cookbook/map.rst.inc

@@ -167,6 +167,7 @@
   * :doc:`/cookbook/security/remember_me`
   * :doc:`/cookbook/security/impersonating_user`
   * :doc:`/cookbook/security/form_login`
+  * :doc:`/cookbook/security/login_handlers`
   * :doc:`/cookbook/security/custom_provider`
   * :doc:`/cookbook/security/custom_password_authenticator`
   * :doc:`/cookbook/security/api_key_authentication`

cookbook/security/index.rst

@@ -12,6 +12,7 @@ Authentication (Identifying/Logging in the User)
     remember_me
     impersonating_user
     form_login
+    login_handlers
     custom_provider
     custom_password_authenticator
     api_key_authentication

cookbook/security/login_handlers.rst

@@ -0,0 +1,197 @@
+.. index::
+   single: Security; Login
+   single: Security; Logout
+   single: Security; Handler
+
+How to Customize the Success and Failure Login Handlers
+=======================================================
+
+After the users successfully log in to your application, they are redirected to
+the proper URL according to the security configuration options. This is done in
+the :class:`Symfony\\Component\\Security\\Http\\Authentication\\DefaultAuthenticationSuccessHandler`
+class and Symfony defines a similar class called
+:class:`Symfony\\Component\\Security\\Http\\Authentication\\DefaultAuthenticationFailureHandler`
+to handle the login failures.
+
+This article explains **how to define your own login handlers** to execute
+custom logic after the user has logged in successfully or failed to do that.
+
+Creating a Success Login Handler
+--------------------------------
+
+First, create a class that implements :class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationSuccessHandlerInterface`
+and add your own logic::
+
+    namespace AppBundle\Security;
+
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface;
+
+    class SuccesfulLoginHandler implements AuthenticationSuccessHandlerInterface
+    {
+        public function onAuthenticationSuccess(Request $request, TokenInterface $token)
+        {
+            // do something...
+
+            // you can inherit from the DefaultAuthenticationSuccessHandler
+            // class to reuse the logic that decides the URL to redirect to
+            return new RedirectResponse(...);
+        }
+    }
+
+Then, define a new service for this login handler:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.security.success_login:
+                class: AppBundle\Security\SuccesfulLoginHandler
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?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">
+
+            <services>
+                <service id="app.security.success_login"
+                         class="AppBundle\Security\SuccesfulLoginHandler">
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        $container->register(
+            'app.security.success_login',
+            'AppBundle\Security\SuccesfulLoginHandler'
+        );
+
+Lastly, add a new ``success_handler`` option under the configuration of the
+firewalls where this handler will be enabled and pass the ``id`` of the service
+as its value:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+            firewalls:
+                main:
+                    # ...
+                    form_login:
+                        success_handler: app.security.successful_login
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="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">
+
+            <config>
+                <!-- ... -->
+                <firewall name="main">
+                    <!-- ... -->
+                    <form-login success-handler="app.security.successful_login" />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            // ...
+            'firewalls' => array(
+                'main' => array(
+                    // ...
+                    'form_login' => array(
+                        'success_handler' => 'app.security.successful_login',
+                    ),
+                ),
+            ),
+        ));
+
+Creating a Failure Login Handler
+--------------------------------
+
+The steps to follow are identical to the ones explained in the previous section.
+First, define your own logic in a class that implements the
+:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationFailureHandlerInterface`
+and create a new service for it. Then, add the ``failure_handler`` configuration
+option in your firewall:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+            firewalls:
+                main:
+                    # ...
+                    form_login:
+                        failure_handler: app.security.failure_login
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="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">
+
+            <config>
+                <!-- ... -->
+                <firewall name="main">
+                    <!-- ... -->
+                    <form-login failure-handler="app.security.failure_login" />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            // ...
+            'firewalls' => array(
+                'main' => array(
+                    // ...
+                    'form_login' => array(
+                        'failure_handler' => 'app.security.failure_login',
+                    ),
+                ),
+            ),
+        ));
+
+When Should Login Handlers Be Used?
+-----------------------------------
+
+These security handlers are closely related to the ``security.authentication.success``
+and ``security.authentication.failure`` events, but Symfony also defines an event
+called ``security.interactive_login`` that lets you customize the behavior of
+the login process.
+
+The success/failure handlers should be used when you need to change the login
+behavior on success/failure by changing the returned ``Response`` object.
+
+The listener hooked into ``security.interactive_login`` should be used when you
+need to execute some code on login success/failure but without altering the
+``Response`` object being sent. For example, to store in a Redis cache the number
+of failed login attempts to protect against brute-force attacks.