Success/failure handlers are not documented

[fabpot]

Working on fixing symfony/symfony#10417, I wanted to update the documentation but there is no documentation for custom success/failure handlers for the firewall configuration. The success_handler and success_failure configuration settings are mentioned in configuration examples, but there is no explanation whatsoever.

I think we need to document them, but only as of Symfony 2.6 as they are less useful before. So, we need to document them in a new cookbook entry, based on the changes done in symfony/symfony#11993.

[wouterj]

We have an open issue for this in #802 We had some issues finding good usecases for such listeners, do you know anything?

[fabpot]

@wouterj Tickets symfony/symfony#5432, symfony/symfony#9272, symfony/symfony#10417, symfony/symfony#11926 talk about some use cases.

[weaverryan]

The use-case I just had (which seems reasonable) is authenticating via AJAX, and so wanting a JSON response back in those cases. But, for non-AJAX, I want to have the normal redirect functionality.

class CustomAuthenticationFailureHandler extends DefaultAuthenticationFailureHandler
{
    /**
     * @var TranslatorInterface
     */
    private $translator;

    public function setTranslator(TranslatorInterface $translator)
    {
        $this->translator = $translator;
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
    {
        if ($request->isXmlHttpRequest()) {
            return new JsonResponse(array(
                'authenticated' => false,
                'error' => $this->translator->trans($exception->getMessageKey(), $exception->getMessageData()),
            ));
        }

        return parent::onAuthenticationFailure($request, $exception);
    }
}

services:
    security.custom_auth_failure_handler:
        class: Knp\UserBundle\Security\Authentication\CustomAuthenticationFailureHandler
        arguments:
            - "@http_kernel"
            - "@security.http_utils"
        calls:
            - [setTranslator, ["@translator"]]

And of course, failure_handler is set to this service id.

If you don't want to extend DefaultAuthenticationFailureHandler, then you can just implement AuthenticationFailureHandlerInterface. But the key is that if you have a setOptions(array $options) method on your failure handler, Symfony will call that and pass you all the things like failure_path, etc. That's the change that happened in symfony/symfony#11993 (which is also why extending DefaultAuthenticationFailureHandler works).

So, I think this can be added, though maybe we should just doc it for 2.6, and backport a few pieces to 2.3. Marking this as actionable :). Imo, we should work these into this article: http://symfony.com/doc/current/cookbook/security/form_login.html, and maybe rename it - it's really all about handling redirect behavior after login - maybe "How to control what happens after a user logs in (or fails login)"