feature #11993 [Security] make it possible to override the default success/failure handler (fabpot)

This PR was merged into the 2.6-dev branch.

Discussion
----------

[Security] make it possible to override the default success/failure handler

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #5432, #9272, #10417, #11926
| License       | MIT
| Doc PR        | symfony/symfony-docs#4258

Overriding the default success/failure handler of the security firewalls is possible via the `success_handler` and `failure_handler` setting but this approach is not flexible as it does not allow you to get the options/provider key.

To sum up the problem:

* Overriding the default success/failure handler is possible via a service;
* When not overridden, the default success/failure handler gets options and the provider key;
* Those options and the provider key are injected by the factory as they are dynamic (they depend on the firewall and the provider key), so getting those options/provider key is not possible for a custom service that is only configured via the container configuration;
* Extending the default handler does not help as the injection mechanism is only triggered when no custom provider is set;
* Wrapping the default handler is not possible as the service id is dynamic.

... and of course we need to keep BC and make it work for people extending the default handler but also for people just using the interface.

Instead of the current PR, I propose this slightly different approach. It's not perfect, but given the above constraint, I think this is an acceptable trade-of.

So, several use cases:

 * Using the default handler (no change);
 * Using a custom handler that implements `AuthenticationSuccessHandlerInterface` directly and does not need any options (no change);
 * Using a custom handler that needs the options/provider key (that's the new use case this PR supports).

This PR introduces 2 new classes that wrap custom handlers. If those classes define the `setOptions()` and/or `setProviderKey()` methods, they are automatically called with the correct arguments. Yours handler does not need to extend the default handler `DefaultAuthentication*Handler`, but doing so helps as the setters are already defined there.

Commits
-------

810eeaf [Security] made it possible to override the default success/failure handler (take 2)
36116fc [Security] made it possible to override the default success/failure handler

4 files changed, 153 insertions, 19 deletions

diff --git a/Http/Authentication/CustomAuthenticationFailureHandler.php b/Http/Authentication/CustomAuthenticationFailureHandler.php
new file mode 100644
index 0000000..35bfc05
--- /dev/null
+++ b/Http/Authentication/CustomAuthenticationFailureHandler.php
@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Http\Authentication;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+
+/**
+ * @author Fabien Potencier <fabien@symfony.com>
+ */
+class CustomAuthenticationFailureHandler implements AuthenticationFailureHandlerInterface
+{
+    private $handler;
+
+    /**
+     * Constructor.
+     *
+     * @param AuthenticationFailureHandlerInterface $handler     An AuthenticationFailureHandlerInterface instance
+     * @param array                                 $options     Options for processing a successful authentication attempt
+     */
+    public function __construct(AuthenticationFailureHandlerInterface $handler, array $options)
+    {
+        $this->handler = $handler;
+        if (method_exists($handler, 'setOptions')) {
+            $this->handler->setOptions($options);
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
+    {
+        return $this->handler->onAuthenticationFailure($request, $exception);
+    }
+}
diff --git a/Http/Authentication/CustomAuthenticationSuccessHandler.php b/Http/Authentication/CustomAuthenticationSuccessHandler.php
new file mode 100644
index 0000000..3e8d8c2
--- /dev/null
+++ b/Http/Authentication/CustomAuthenticationSuccessHandler.php
@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Http\Authentication;
+
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\HttpFoundation\Request;
+
+/**
+ * @author Fabien Potencier <fabien@symfony.com>
+ */
+class CustomAuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
+{
+    private $handler;
+
+    /**
+     * Constructor.
+     *
+     * @param AuthenticationSuccessHandlerInterface $handler     An AuthenticationFailureHandlerInterface instance
+     * @param array                                 $options     Options for processing a successful authentication attempt
+     * @param string                                $providerKey The provider key
+     */
+    public function __construct(AuthenticationSuccessHandlerInterface $handler, array $options, $providerKey)
+    {
+        $this->handler = $handler;
+        if (method_exists($handler, 'setOptions')) {
+            $this->handler->setOptions($options);
+        }
+        if (method_exists($providerKey, 'setProviderKey')) {
+            $this->handler->setProviderKey($providerKey);
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function onAuthenticationSuccess(Request $request, TokenInterface $token)
+    {
+        return $this->handler->onAuthenticationSuccess($request, $token);
+    }
+}
diff --git a/Http/Authentication/DefaultAuthenticationFailureHandler.php b/Http/Authentication/DefaultAuthenticationFailureHandler.php
index db96e67..658a999 100644
--- a/Http/Authentication/DefaultAuthenticationFailureHandler.php
+++ b/Http/Authentication/DefaultAuthenticationFailureHandler.php
@@ -34,6 +34,12 @@ class DefaultAuthenticationFailureHandler implements AuthenticationFailureHandle
     protected $httpUtils;
     protected $logger;
     protected $options;
+    protected $defaultOptions = array(
+        'failure_path'           => null,
+        'failure_forward'        => false,
+        'login_path'             => '/login',
+        'failure_path_parameter' => '_failure_path',
+    );
 
     /**
      * Constructor.
@@ -43,18 +49,32 @@ class DefaultAuthenticationFailureHandler implements AuthenticationFailureHandle
      * @param array               $options    Options for processing a failed authentication attempt.
      * @param LoggerInterface     $logger     Optional logger
      */
-    public function __construct(HttpKernelInterface $httpKernel, HttpUtils $httpUtils, array $options, LoggerInterface $logger = null)
+    public function __construct(HttpKernelInterface $httpKernel, HttpUtils $httpUtils, array $options = array(), LoggerInterface $logger = null)
     {
         $this->httpKernel = $httpKernel;
-        $this->httpUtils  = $httpUtils;
-        $this->logger     = $logger;
+        $this->httpUtils = $httpUtils;
+        $this->logger = $logger;
+        $this->setOptions($options);
+    }
 
-        $this->options = array_merge(array(
-            'failure_path'           => null,
-            'failure_forward'        => false,
-            'login_path'             => '/login',
-            'failure_path_parameter' => '_failure_path',
-        ), $options);
+    /**
+     * Gets the options.
+     *
+     * @return array An array of options
+     */
+    public function getOptions()
+    {
+        return $this->options;
+    }
+
+    /**
+     * Sets the options.
+     *
+     * @param array $options An array of options
+     */
+    public function setOptions(array $options)
+    {
+        $this->options = array_merge($this->defaultOptions, $options);
     }
 
     /**
diff --git a/Http/Authentication/DefaultAuthenticationSuccessHandler.php b/Http/Authentication/DefaultAuthenticationSuccessHandler.php
index 54d6fc1..0ee11b4 100644
--- a/Http/Authentication/DefaultAuthenticationSuccessHandler.php
+++ b/Http/Authentication/DefaultAuthenticationSuccessHandler.php
@@ -27,6 +27,13 @@ class DefaultAuthenticationSuccessHandler implements AuthenticationSuccessHandle
     protected $httpUtils;
     protected $options;
     protected $providerKey;
+    protected $defaultOptions = array(
+        'always_use_default_target_path' => false,
+        'default_target_path'            => '/',
+        'login_path'                     => '/login',
+        'target_path_parameter'          => '_target_path',
+        'use_referer'                    => false,
+    );
 
     /**
      * Constructor.
@@ -34,17 +41,10 @@ class DefaultAuthenticationSuccessHandler implements AuthenticationSuccessHandle
      * @param HttpUtils $httpUtils
      * @param array     $options   Options for processing a successful authentication attempt.
      */
-    public function __construct(HttpUtils $httpUtils, array $options)
+    public function __construct(HttpUtils $httpUtils, array $options = array())
     {
-        $this->httpUtils   = $httpUtils;
-
-        $this->options = array_merge(array(
-            'always_use_default_target_path' => false,
-            'default_target_path'            => '/',
-            'login_path'                     => '/login',
-            'target_path_parameter'          => '_target_path',
-            'use_referer'                    => false,
-        ), $options);
+        $this->httpUtils = $httpUtils;
+        $this->setOptions($options);
     }
 
     /**
@@ -56,6 +56,26 @@ class DefaultAuthenticationSuccessHandler implements AuthenticationSuccessHandle
     }
 
     /**
+     * Gets the options.
+     *
+     * @return array An array of options
+     */
+    public function getOptions()
+    {
+        return $this->options;
+    }
+
+    /**
+     * Sets the options.
+     *
+     * @param array $options An array of options
+     */
+    public function setOptions(array $options)
+    {
+        $this->options = array_merge($this->defaultOptions, $options);
+    }
+
+    /**
      * Get the provider key.
      *
      * @return string