feature #18135 [Security] Deprecate onAuthenticationSuccess() (weaverryan)

This PR was squashed before being merged into the 3.1-dev branch (closes #18135).

Discussion
----------

[Security] Deprecate onAuthenticationSuccess()

| Q             | A
| ------------- | ---
| Branch        | master
| Bug fix?      | yes
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #18027
| License       | MIT
| Doc PR        | not yet - the existing feature is not currently documented

Because of the new `TargetPathTrait`, implementing `onAuthenticationSuccess` yourself is quite easy. I think we should just remove it. This also will fix #18027.

Thanks!

Commits
-------

c4ae80a [Security] Deprecate onAuthenticationSuccess()

src/Symfony/Component/Security/Guard/Authenticator/AbstractFormLoginAuthenticator.php

@@ -35,16 +35,6 @@ abstract class AbstractFormLoginAuthenticator extends AbstractGuardAuthenticator
      */
     abstract protected function getLoginUrl();
 
-    /**
-     * The user will be redirected to the secure page they originally tried
-     * to access. But if no such page exists (i.e. the user went to the
-     * login page directly), this returns the URL the user should be redirected
-     * to after logging in successfully (e.g. your homepage).
-     *
-     * @return string
-     */
-    abstract protected function getDefaultSuccessRedirectUrl();
-
     /**
      * Override to change what happens after a bad username/password is submitted.
      *
@@ -72,7 +62,13 @@ abstract class AbstractFormLoginAuthenticator extends AbstractGuardAuthenticator
      */
     public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey)
     {
-        // if the user hit a secure page and start() was called, this was
+        @trigger_error(sprintf('The AbstractFormLoginAuthenticator::onAuthenticationSuccess() implementation was deprecated in Symfony 3.1 and will be removed in Symfony 4.0. You should implement this method yourself in %s and remove getDefaultSuccessRedirectUrl().', get_class($this)), E_USER_DEPRECATED);
+
+        if (!method_exists($this, 'getDefaultSuccessRedirectUrl')) {
+            throw new \Exception(sprintf('You must implement onAuthenticationSuccess() or getDefaultSuccessRedirectURL() in %s.', get_class($this)));
+        }
+
+        // if the user hits a secure page and start() was called, this was
         // the URL they were on, and probably where you want to redirect to
         $targetPath = $this->getTargetPath($request->getSession(), $providerKey);
 

src/Symfony/Component/Security/Guard/Tests/Authenticator/AbstractFormLoginAuthenticatorTest.php

@@ -0,0 +1,64 @@
+<?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\Guard\Tests\Authenticator;
+
+use Symfony\Component\HttpFoundation\RedirectResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Security\Core\User\UserInterface;
+use Symfony\Component\Security\Core\User\UserProviderInterface;
+use Symfony\Component\Security\Guard\Authenticator\AbstractFormLoginAuthenticator;
+
+class AbstractFormLoginAuthenticatorTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @group legacy
+     */
+    public function testLegacyWithLoginUrl()
+    {
+        $request = new Request();
+        $request->setSession($this->getMock('Symfony\Component\HttpFoundation\Session\Session'));
+
+        $authenticator = new LegacyFormLoginAuthenticator();
+        /** @var RedirectResponse $actualResponse */
+        $actualResponse = $authenticator->onAuthenticationSuccess(
+            $request,
+            $this->getMock('Symfony\Component\Security\Core\Authentication\Token\TokenInterface'),
+            'provider_key'
+        );
+
+        $this->assertEquals('/default_url', $actualResponse->getTargetUrl());
+    }
+}
+
+class LegacyFormLoginAuthenticator extends AbstractFormLoginAuthenticator
+{
+    protected function getDefaultSuccessRedirectUrl()
+    {
+        return '/default_url';
+    }
+
+    protected function getLoginUrl()
+    {
+    }
+
+    public function getCredentials(Request $request)
+    {
+    }
+
+    public function getUser($credentials, UserProviderInterface $userProvider)
+    {
+    }
+
+    public function checkCredentials($credentials, UserInterface $user)
+    {
+    }
+}