feature #143 helper methods for storing ResetPasswordToken in session (jrushlow)

This PR was squashed before being merged into the master branch.

Discussion
----------

helper methods for storing ResetPasswordToken in session

It is more desireable to store the `ResetPasswordToken::class` object in the session after it has been generated by the helper vs storing individual properties of the token class in the session.

Adds the following `ResetPasswordControllerTrait::class` methods:
- `setTokenObjectInSession(ResetPasswordToken $token): void`
- `getTokenObjectFromSession(): ?ResetPasswordToken`

Deprecates the following `ResetPasswordControllerTrait:class` methods:
- `setCanCheckEmailInSession()`
- `canCheckEmail()`

These will be removed in version `2.0` of this bundle.

refs #142

Commits
-------

ebbb9ef helper methods for storing ResetPasswordToken in session

Author: weaverryan

CHANGELOG.md

@@ -5,6 +5,10 @@ find a change that break's semver, please create an issue.*
 
 ## NEXT
 
+- [#143](https://github.com/SymfonyCasts/reset-password-bundle/pull/143) Adds controller trait methods to set/get the 
+  `ResetPasswordToken::class` object in the session. The following `ResetPasswordControllerTrait::class` methods have been deprecated: 
+  `setCanCheckEmailInSession()`, `canCheckEmail()`
+
 ## v1.2.2
 
 - [#139](https://github.com/SymfonyCasts/reset-password-bundle/pull/139) Fixed regression

src/Controller/ResetPasswordControllerTrait.php

@@ -11,6 +11,7 @@
 
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Session\SessionInterface;
+use SymfonyCasts\Bundle\ResetPassword\Model\ResetPasswordToken;
 
 /**
  * Provides useful methods to a "reset password controller".
@@ -23,13 +24,31 @@
  */
 trait ResetPasswordControllerTrait
 {
+    /**
+     * @deprecated since 1.3.0, use ResetPasswordControllerTrait::setTokenObjectInSession() instead.
+     */
     private function setCanCheckEmailInSession(): void
     {
+        trigger_deprecation(
+            'symfonycasts/reset-password-bundle',
+            '1.3.0',
+            'Storing the ResetPasswordToken object in the session is more desirable, use ResetPasswordControllerTrait::setTokenObjectInSession() instead.'
+        );
+
         $this->getSessionService()->set('ResetPasswordCheckEmail', true);
     }
 
+    /**
+     * @deprecated since 1.3.0, use ResetPasswordControllerTrait::getTokenObjectFromSession() instead.
+     */
     private function canCheckEmail(): bool
     {
+        trigger_deprecation(
+            'symfonycasts/reset-password-bundle',
+            '1.3.0',
+            'Storing the ResetPasswordToken object in the session is more desirable, use ResetPasswordControllerTrait::getTokenObjectFromSession() instead.'
+        );
+
         return $this->getSessionService()->has('ResetPasswordCheckEmail');
     }
 
@@ -43,12 +62,25 @@ private function getTokenFromSession(): ?string
         return $this->getSessionService()->get('ResetPasswordPublicToken');
     }
 
+    private function setTokenObjectInSession(ResetPasswordToken $token): void
+    {
+        $token->clearToken();
+
+        $this->getSessionService()->set('ResetPasswordToken', $token);
+    }
+
+    private function getTokenObjectFromSession(): ?ResetPasswordToken
+    {
+        return $this->getSessionService()->get('ResetPasswordToken');
+    }
+
     private function cleanSessionAfterReset(): void
     {
         $session = $this->getSessionService();
 
         $session->remove('ResetPasswordPublicToken');
         $session->remove('ResetPasswordCheckEmail');
+        $session->remove('ResetPasswordToken');
     }
 
     private function getSessionService(): SessionInterface

src/Model/ResetPasswordToken.php

@@ -16,7 +16,7 @@
 final class ResetPasswordToken
 {
     /**
-     * @var string selector + non-hashed verifier token
+     * @var string|null selector + non-hashed verifier token
      */
     private $token;
 
@@ -55,9 +55,21 @@ public function __construct(string $token, \DateTimeInterface $expiresAt, int $g
      */
     public function getToken(): string
     {
+        if (null === $this->token) {
+            throw new \RuntimeException('The token property is not set. Calling getToken() after calling clearToken() is not allowed.');
+        }
+
         return $this->token;
     }
 
+    /**
+     * Allow the token object to be safely persisted in a session.
+     */
+    public function clearToken(): void
+    {
+        $this->token = null;
+    }
+
     public function getExpiresAt(): \DateTimeInterface
     {
         return $this->expiresAt;

tests/UnitTests/Controller/ResetPasswordControllerTraitTest.php

@@ -16,6 +16,7 @@
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\HttpFoundation\Session\SessionInterface;
 use SymfonyCasts\Bundle\ResetPassword\Controller\ResetPasswordControllerTrait;
+use SymfonyCasts\Bundle\ResetPassword\Model\ResetPasswordToken;
 
 /**
  * @author Jesse Rushlow <jr@rushlow.dev>
@@ -25,6 +26,7 @@ class ResetPasswordControllerTraitTest extends TestCase
 {
     private const EMAIL_KEY = 'ResetPasswordCheckEmail';
     private const TOKEN_KEY = 'ResetPasswordPublicToken';
+    private const TOKEN_OBJECT_KEY = 'ResetPasswordToken';
 
     /**
      * @var MockObject|SessionInterface
@@ -64,6 +66,9 @@ public function testGetsTokenFromSession(): void
         $fixture->getToken();
     }
 
+    /**
+     * @group legacy
+     */
     public function testSetsEmailFlagInSession(): void
     {
         $this->mockSession
@@ -76,6 +81,9 @@ public function testSetsEmailFlagInSession(): void
         $fixture->setEmail();
     }
 
+    /**
+     * @group legacy
+     */
     public function testCanCheckEmailUsesCorrectKey(): void
     {
         $this->mockSession
@@ -89,12 +97,43 @@ public function testCanCheckEmailUsesCorrectKey(): void
         $fixture->getEmail();
     }
 
+    public function testSetsResetTokenInSession(): void
+    {
+        $token = new ResetPasswordToken('1234', new \DateTimeImmutable(), 1234);
+
+        $this->mockSession
+            ->expects($this->once())
+            ->method('set')
+            ->with(self::TOKEN_OBJECT_KEY, $token)
+        ;
+
+        $fixture = $this->getFixture();
+        $fixture->storeResetPasswordToken($token);
+    }
+
+    public function testGetsResetTokenFromSession(): void
+    {
+        $token = new ResetPasswordToken('1234', new \DateTimeImmutable(), 1234);
+
+        $this->mockSession
+            ->expects($this->once())
+            ->method('get')
+            ->with(self::TOKEN_OBJECT_KEY)
+            ->willReturn($token)
+        ;
+
+        $fixture = $this->getFixture();
+        $result = $fixture->getResetPasswordToken();
+
+        self::assertSame($token, $result);
+    }
+
     public function testCleanSessionAfterServiceRemovesByTokenAndEmailKeys(): void
     {
         $this->mockSession
-            ->expects($this->exactly(2))
+            ->expects($this->exactly(3))
             ->method('remove')
-            ->withConsecutive([self::TOKEN_KEY], [self::EMAIL_KEY])
+            ->withConsecutive([self::TOKEN_KEY], [self::EMAIL_KEY], [self::TOKEN_OBJECT_KEY])
         ;
 
         $fixture = $this->getFixture();
@@ -165,6 +204,16 @@ public function getToken(): string
                 return $this->getTokenFromSession();
             }
 
+            public function storeResetPasswordToken(ResetPasswordToken $token): void
+            {
+                $this->setTokenObjectInSession($token);
+            }
+
+            public function getResetPasswordToken(): ?ResetPasswordToken
+            {
+                return $this->getTokenObjectFromSession();
+            }
+
             public function clearSession(): void
             {
                 $this->cleanSessionAfterReset();

tests/UnitTests/Model/ResetPasswordTokenTest.php

@@ -17,6 +17,18 @@
  */
 class ResetPasswordTokenTest extends TestCase
 {
+    public function testTokenValueIsSafeForStorage(): void
+    {
+        $token = new ResetPasswordToken('1234', new \DateTimeImmutable(), \time());
+
+        $token->clearToken();
+
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('The token property is not set. Calling getToken() after calling clearToken() is not allowed.');
+
+        self::assertSame('void', $token->getToken());
+    }
+
     /**
      * @dataProvider translationIntervalDataProvider
      */