feature #17714 Adding new TargetPathTrait to get/set the authentication "target_path" (weaverryan)

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

Discussion
----------

Adding new TargetPathTrait to get/set the authentication "target_path"

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | not yet...

Hi guys!

This is a small guy. Basically, when you're doing custom auth (i.e. a guard authenticator), it's common to need the previous URL the user tried to get to (i.e. the "target path"). It's not much work to do it now, but it's very abstract - needing to know a weird string pattern. This just wraps that weirdness up in a simple function (`getTargetPath()`).

Thanks!

Commits
-------

18dfe37 Adding new TargetPathTrait to get/set the authentication "target_path"

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

@@ -17,6 +17,7 @@ use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\Security;
+use Symfony\Component\Security\Http\Util\TargetPathTrait;
 
 /**
  * A base class to make form login authentication easier!
@@ -25,6 +26,8 @@ use Symfony\Component\Security\Core\Security;
  */
 abstract class AbstractFormLoginAuthenticator extends AbstractGuardAuthenticator
 {
+    use TargetPathTrait;
+
     /**
      * Return the URL to the login page.
      *
@@ -71,7 +74,7 @@ abstract class AbstractFormLoginAuthenticator extends AbstractGuardAuthenticator
     {
         // if the user hit a secure page and start() was called, this was
         // the URL they were on, and probably where you want to redirect to
-        $targetPath = $request->getSession()->get('_security.'.$providerKey.'.target_path');
+        $targetPath = $this->getTargetPath($request->getSession(), $providerKey);
 
         if (!$targetPath) {
             $targetPath = $this->getDefaultSuccessRedirectUrl();

src/Symfony/Component/Security/Http/Authentication/DefaultAuthenticationSuccessHandler.php

@@ -13,6 +13,7 @@ namespace Symfony\Component\Security\Http\Authentication;
 
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Security\Http\Util\TargetPathTrait;
 use Symfony\Component\Security\Http\HttpUtils;
 use Symfony\Component\Security\Http\ParameterBagUtils;
 
@@ -25,6 +26,8 @@ use Symfony\Component\Security\Http\ParameterBagUtils;
  */
 class DefaultAuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
 {
+    use TargetPathTrait;
+
     protected $httpUtils;
     protected $options;
     protected $providerKey;
@@ -113,8 +116,8 @@ class DefaultAuthenticationSuccessHandler implements AuthenticationSuccessHandle
             return $targetUrl;
         }
 
-        if (null !== $this->providerKey && $targetUrl = $request->getSession()->get('_security.'.$this->providerKey.'.target_path')) {
-            $request->getSession()->remove('_security.'.$this->providerKey.'.target_path');
+        if (null !== $this->providerKey && $targetUrl = $this->getTargetPath($request->getSession(), $this->providerKey)) {
+            $this->removeTargetPath($request->getSession(), $this->providerKey);
 
             return $targetUrl;
         }

src/Symfony/Component/Security/Http/Firewall/ExceptionListener.php

@@ -22,6 +22,7 @@ use Symfony\Component\Security\Core\Exception\AuthenticationException;
 use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 use Symfony\Component\Security\Core\Exception\InsufficientAuthenticationException;
 use Symfony\Component\Security\Core\Exception\LogoutException;
+use Symfony\Component\Security\Http\Util\TargetPathTrait;
 use Symfony\Component\Security\Http\HttpUtils;
 use Symfony\Component\HttpFoundation\Request;
 use Psr\Log\LoggerInterface;
@@ -39,6 +40,8 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
  */
 class ExceptionListener
 {
+    use TargetPathTrait;
+
     private $tokenStorage;
     private $providerKey;
     private $accessDeniedHandler;
@@ -210,7 +213,7 @@ class ExceptionListener
     {
         // session isn't required when using HTTP basic authentication mechanism for example
         if ($request->hasSession() && $request->isMethodSafe() && !$request->isXmlHttpRequest()) {
-            $request->getSession()->set('_security.'.$this->providerKey.'.target_path', $request->getUri());
+            $this->saveTargetPath($request->getSession(), $this->providerKey, $request->getUri());
         }
     }
 }

src/Symfony/Component/Security/Http/Tests/Util/TargetPathTraitTest.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Symfony\Component\Security\Http\Tests\Util;
+
+use Symfony\Component\HttpFoundation\Session\SessionInterface;
+use Symfony\Component\Security\Http\Util\TargetPathTrait;
+
+class TargetPathTraitTest extends \PHPUnit_Framework_TestCase
+{
+    public function testSetTargetPath()
+    {
+        $obj = new TestClassWithTargetPathTrait();
+
+        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\SessionInterface')
+                    ->getMock();
+
+        $session->expects($this->once())
+            ->method('set')
+            ->with('_security.firewall_name.target_path', '/foo');
+
+        $obj->doSetTargetPath($session, 'firewall_name', '/foo');
+    }
+
+    public function testGetTargetPath()
+    {
+        $obj = new TestClassWithTargetPathTrait();
+
+        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\SessionInterface')
+                    ->getMock();
+
+        $session->expects($this->once())
+            ->method('get')
+            ->with('_security.cool_firewall.target_path')
+            ->willReturn('/bar');
+
+        $actualUri = $obj->doGetTargetPath($session, 'cool_firewall');
+        $this->assertEquals(
+            '/bar',
+            $actualUri
+        );
+    }
+
+    public function testRemoveTargetPath()
+    {
+        $obj = new TestClassWithTargetPathTrait();
+
+        $session = $this->getMockBuilder('Symfony\Component\HttpFoundation\Session\SessionInterface')
+                    ->getMock();
+
+        $session->expects($this->once())
+            ->method('remove')
+            ->with('_security.best_firewall.target_path');
+
+        $obj->doRemoveTargetPath($session, 'best_firewall');
+    }
+}
+
+class TestClassWithTargetPathTrait
+{
+    use TargetPathTrait;
+
+    public function doSetTargetPath(SessionInterface $session, $providerKey, $uri)
+    {
+        $this->saveTargetPath($session, $providerKey, $uri);
+    }
+
+    public function doGetTargetPath(SessionInterface $session, $providerKey)
+    {
+        return $this->getTargetPath($session, $providerKey);
+    }
+
+    public function doRemoveTargetPath(SessionInterface $session, $providerKey)
+    {
+        $this->removeTargetPath($session, $providerKey);
+    }
+}

src/Symfony/Component/Security/Http/Util/TargetPathTrait.php

@@ -0,0 +1,58 @@
+<?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\Util;
+
+use Symfony\Component\HttpFoundation\Session\SessionInterface;
+
+/**
+ * Trait to get (and set) the URL the user last visited before being forced to authenticate.
+ */
+trait TargetPathTrait
+{
+    /**
+     * Set the target path the user should be redirected to after authentication.
+     *
+     * Usually, you do not need to set this directly.
+     *
+     * @param SessionInterface $session
+     * @param string           $providerKey The name of your firewall
+     * @param string           $uri         The URI to set as the target path
+     */
+    private function saveTargetPath(SessionInterface $session, $providerKey, $uri)
+    {
+        $session->set('_security.'.$providerKey.'.target_path', $uri);
+    }
+
+    /**
+     * Returns the URL (if any) the user visited that forced them to login.
+     *
+     * @param SessionInterface $session
+     * @param string           $providerKey The name of your firewall
+     *
+     * @return string
+     */
+    private function getTargetPath(SessionInterface $session, $providerKey)
+    {
+        return $session->get('_security.'.$providerKey.'.target_path');
+    }
+
+    /**
+     * Removes the target path from the session.
+     *
+     * @param SessionInterface $session
+     * @param string           $providerKey The name of your firewall
+     */
+    private function removeTargetPath(SessionInterface $session, $providerKey)
+    {
+        $session->remove('_security.'.$providerKey.'.target_path');
+    }
+}