[Security] Improve BC-layer to deprecate eraseCredentials methods

Author: nicolas-grekas

Authentication/Token/AbstractToken.php

@@ -62,11 +62,11 @@ public function setUser(UserInterface $user): void
     /**
      * Removes sensitive information from the token.
      *
-     * @deprecated since Symfony 7.3
+     * @deprecated since Symfony 7.3, erase credentials using the "__serialize()" method instead
      */
     public function eraseCredentials(): void
     {
-        trigger_deprecation('symfony/security-core', '7.3', sprintf('The "%s()" method is deprecated and will be removed in 8.0, use a DTO instead or implement your own erasing logic if needed.', __METHOD__));
+        trigger_deprecation('symfony/security-core', '7.3', \sprintf('The "%s::eraseCredentials()" method is deprecated and will be removed in 8.0, erase credentials using the "__serialize()" method instead.', TokenInterface::class));
 
         if ($this->getUser() instanceof UserInterface) {
             $this->getUser()->eraseCredentials();

Authentication/Token/NullToken.php

@@ -44,12 +44,14 @@ public function getUserIdentifier(): string
     }
 
     /**
-     * Removes sensitive information from the token.
-     *
      * @deprecated since Symfony 7.3
      */
+    #[\Deprecated(since: 'symfony/security-core 7.3')]
     public function eraseCredentials(): void
     {
+        if (\PHP_VERSION_ID < 80400) {
+            @trigger_error(\sprintf('Method %s::eraseCredentials() is deprecated since symfony/security-core 7.3', self::class), \E_USER_DEPRECATED);
+        }
     }
 
     public function getAttributes(): array

Authentication/Token/TokenInterface.php

@@ -16,6 +16,9 @@
 /**
  * TokenInterface is the interface for the user authentication information.
  *
+ * The __serialize/__unserialize() magic methods can be implemented on the token
+ * class to prevent sensitive credentials from being put in the session storage.
+ *
  * @author Fabien Potencier <fabien@symfony.com>
  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  */
@@ -57,8 +60,7 @@ public function setUser(UserInterface $user): void;
     /**
      * Removes sensitive information from the token.
      *
-     * @deprecated since Symfony 7.3, use a dedicated DTO instead or implement your
-     *             own erasing logic instead
+     * @deprecated since Symfony 7.3; erase credentials using the "__serialize()" method instead
      */
     public function eraseCredentials(): void;
 

CHANGELOG.md

@@ -8,7 +8,7 @@ CHANGELOG
    For example, users not currently logged in, or while processing a message from a message queue.
  * Add `OfflineTokenInterface` to mark tokens that do not represent the currently logged-in user
  * Deprecate `UserInterface::eraseCredentials()` and `TokenInterface::eraseCredentials()`,
-   use a dedicated DTO or erase credentials on your own e.g. upon `AuthenticationTokenCreatedEvent` instead
+   erase credentials e.g. using `__serialize()` instead
 
 7.2
 ---

Tests/Authentication/AuthenticationTrustResolverTest.php

@@ -119,6 +119,7 @@ public function getUserIdentifier(): string
     {
     }
 
+    #[\Deprecated]
     public function eraseCredentials(): void
     {
     }

Tests/Authentication/Token/AbstractTokenTest.php

@@ -14,6 +14,7 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\Security\Core\Authentication\Token\AbstractToken;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\Security\Core\User\InMemoryUser;
 use Symfony\Component\Security\Core\User\UserInterface;
 
@@ -46,7 +47,8 @@ public function testEraseCredentials()
         $user = $this->createMock(UserInterface::class);
         $user->expects($this->once())->method('eraseCredentials');
         $token->setUser($user);
-        $this->expectDeprecation('The Symfony\Component\Security\Core\User\UserInterface::eraseCredentials method is deprecated (since Symfony 7.3, use a dedicated DTO instead or implement your own erasing logic instead).');
+
+        $this->expectDeprecation(\sprintf('Since symfony/security-core 7.3: The "%s::eraseCredentials()" method is deprecated and will be removed in 8.0, erase credentials using the "__serialize()" method instead.', TokenInterface::class));
 
         $token->eraseCredentials();
     }

Tests/Authentication/Token/Fixtures/CustomUser.php

@@ -31,6 +31,12 @@ public function getRoles(): array
         return $this->roles;
     }
 
+    public function getPassword(): ?string
+    {
+        return null;
+    }
+
+    #[\Deprecated]
     public function eraseCredentials(): void
     {
     }

Tests/User/InMemoryUserTest.php

@@ -12,11 +12,14 @@
 namespace Symfony\Component\Security\Core\Tests\User;
 
 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\Security\Core\User\InMemoryUser;
 use Symfony\Component\Security\Core\User\UserInterface;
 
 class InMemoryUserTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
     public function testConstructorException()
     {
         $this->expectException(\InvalidArgumentException::class);
@@ -59,6 +62,7 @@ public function testIsEnabled()
     public function testEraseCredentials()
     {
         $user = new InMemoryUser('fabien', 'superpass');
+        $this->expectDeprecation(\sprintf('%sMethod %s::eraseCredentials() is deprecated since symfony/security-core 7.3', \PHP_VERSION_ID >= 80400 ? 'Unsilenced deprecation: ' : '', InMemoryUser::class));
         $user->eraseCredentials();
         $this->assertEquals('superpass', $user->getPassword());
     }

User/InMemoryUser.php

@@ -74,9 +74,15 @@ public function isEnabled(): bool
         return $this->enabled;
     }
 
+    /**
+     * @deprecated since Symfony 7.3
+     */
+    #[\Deprecated(since: 'symfony/security-core 7.3')]
     public function eraseCredentials(): void
     {
-        trigger_deprecation('symfony/security-core', '7.3', sprintf('The "%s()" method is deprecated and will be removed in 8.0, use a DTO instead or implement your own erasing logic if needed.', __METHOD__));
+        if (\PHP_VERSION_ID < 80400) {
+            @trigger_error(\sprintf('Method %s::eraseCredentials() is deprecated since symfony/security-core 7.3', self::class), \E_USER_DEPRECATED);
+        }
     }
 
     public function isEqualTo(UserInterface $user): bool

User/OidcUser.php

@@ -71,8 +71,15 @@ public function getUserIdentifier(): string
         return (string) ($this->userIdentifier ?? $this->getSub());
     }
 
+    /**
+     * @deprecated since Symfony 7.3
+     */
+    #[\Deprecated(since: 'symfony/security-core 7.3')]
     public function eraseCredentials(): void
     {
+        if (\PHP_VERSION_ID < 80400) {
+            @trigger_error(\sprintf('Method %s::eraseCredentials() is deprecated since symfony/security-core 7.3', self::class), \E_USER_DEPRECATED);
+        }
     }
 
     public function getSub(): ?string