Make needsPreparation a soft requirement to prevent b/c break

Prior to this change, the needsPreparation method would break existing
implementations.

This change makes the change not break existing TwoFactorProviders by not actually defining the `needsPreparation` in the interface.
This is to be implemented in version 9 of the 2fa package.

Author: johanib

src/bundle/Security/TwoFactor/Provider/TwoFactorProviderInitiator.php

@@ -10,6 +10,9 @@
 use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Exception\UnknownTwoFactorProviderException;
 use function array_walk;
 use function count;
+use function method_exists;
+use function trigger_error;
+use const E_USER_DEPRECATED;
 
 /**
  * @final
@@ -34,7 +37,15 @@ public function beginTwoFactorAuthentication(AuthenticationContextInterface $con
             }
 
             $activeTwoFactorProviders[] = $providerName;
-            if ($provider->needsPreparation()) {
+
+            if (!method_exists($provider, 'needsPreparation')) {
+                @trigger_error(
+                    'Two-factor provider "'.$providerName.'" does not implement needsPreparation() method. This method will be required in the next major version.',
+                    E_USER_DEPRECATED,
+                );
+            }
+
+            if (!method_exists($provider, 'needsPreparation') || $provider->needsPreparation()) {
                 continue;
             }
 

src/bundle/Security/TwoFactor/Provider/TwoFactorProviderInterface.php

@@ -15,8 +15,12 @@ public function beginAuthentication(AuthenticationContextInterface $context): bo
 
     /**
      * Determine whether this Provider needs to be prepared (if the prepareAuthentication method needs to be called).
+     *
+     * In version 9, this method will be introduced, and all providers will need to implement it.
+     * Currently, it will be called, but is not required.
+     *
+     * public function needsPreparation(): bool;
      */
-    public function needsPreparation(): bool;
 
     /**
      * Do all steps necessary to prepare authentication, e.g. generate & send a code.

tests/Security/TwoFactor/Provider/MockTwoFactorProvider.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scheb\TwoFactorBundle\Tests\Security\TwoFactor\Provider;
+
+use RuntimeException;
+use Scheb\TwoFactorBundle\Security\TwoFactor\AuthenticationContextInterface;
+use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorFormRendererInterface;
+use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderInterface;
+
+class MockTwoFactorProvider implements TwoFactorProviderInterface
+{
+    private bool $beginAuthenticationResult = false;
+    private int $beginAuthenticationCallCount = 0;
+    private AuthenticationContextInterface|null $lastContext = null;
+
+    public function __construct(private readonly bool $needsPreparation = false)
+    {
+    }
+
+    public function setBeginAuthenticationResult(bool $result): void
+    {
+        $this->beginAuthenticationResult = $result;
+    }
+
+    public function getBeginAuthenticationCallCount(): int
+    {
+        return $this->beginAuthenticationCallCount;
+    }
+
+    public function getLastContext(): AuthenticationContextInterface|null
+    {
+        return $this->lastContext;
+    }
+
+    public function beginAuthentication(AuthenticationContextInterface $context): bool
+    {
+        ++$this->beginAuthenticationCallCount;
+        $this->lastContext = $context;
+
+        return $this->beginAuthenticationResult;
+    }
+
+    public function needsPreparation(): bool
+    {
+        return $this->needsPreparation;
+    }
+
+    public function prepareAuthentication(object $user): void
+    {
+        // Mock implementation
+    }
+
+    public function validateAuthenticationCode(object $user, string $authenticationCode): bool
+    {
+        return false;
+    }
+
+    public function getFormRenderer(): TwoFactorFormRendererInterface
+    {
+        throw new RuntimeException('Not implemented in mock');
+    }
+}

tests/Security/TwoFactor/Provider/TwoFactorProviderInitiatorTest.php

@@ -11,24 +11,21 @@
 use Scheb\TwoFactorBundle\Security\Authentication\Token\TwoFactorTokenInterface;
 use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderDeciderInterface;
 use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderInitiator;
-use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderInterface;
 use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorProviderRegistry;
 use Scheb\TwoFactorBundle\Tests\Security\TwoFactor\Condition\AbstractAuthenticationContextTestCase;
 
 class TwoFactorProviderInitiatorTest extends AbstractAuthenticationContextTestCase
 {
     private MockObject&TwoFactorTokenFactoryInterface $twoFactorTokenFactory;
-    private MockObject&TwoFactorProviderInterface $provider1;
-    private MockObject&TwoFactorProviderInterface $provider2;
+    private MockTwoFactorProvider $provider1;
+    private MockTwoFactorProvider $provider2;
     private MockObject&TwoFactorProviderDeciderInterface $providerDecider;
     private TwoFactorProviderInitiator $initiator;
 
     protected function setUp(): void
     {
-        $this->provider1 = $this->createMock(TwoFactorProviderInterface::class);
-        $this->provider1->method('needsPreparation')->willReturn(true);
-        $this->provider2 = $this->createMock(TwoFactorProviderInterface::class);
-        $this->provider2->method('needsPreparation')->willReturn(false);
+        $this->provider1 = new MockTwoFactorProvider(needsPreparation: true);
+        $this->provider2 = new MockTwoFactorProvider(needsPreparation: false);
 
         $providerRegistry = $this->createMock(TwoFactorProviderRegistry::class);
         $providerRegistry
@@ -74,15 +71,8 @@ private function createUserWithPreferredProvider(string $preferredProvider): Moc
 
     private function stubProvidersReturn(bool $provider1Returns, bool $provider2Returns): void
     {
-        $this->provider1
-            ->expects($this->any())
-            ->method('beginAuthentication')
-            ->willReturn($provider1Returns);
-
-        $this->provider2
-            ->expects($this->any())
-            ->method('beginAuthentication')
-            ->willReturn($provider2Returns);
+        $this->provider1->setBeginAuthenticationResult($provider1Returns);
+        $this->provider2->setBeginAuthenticationResult($provider2Returns);
     }
 
     private function stubTwoFactorTokenFactoryReturns(MockObject $token): void
@@ -106,17 +96,12 @@ public function beginAuthentication_multipleProviders_beginAuthenticationOnEachT
     {
         $context = $this->createAuthenticationContext();
 
-        $this->provider1
-            ->expects($this->once())
-            ->method('beginAuthentication')
-            ->with($context);
-
-        $this->provider2
-            ->expects($this->once())
-            ->method('beginAuthentication')
-            ->with($context);
-
         $this->initiator->beginTwoFactorAuthentication($context);
+
+        $this->assertSame(1, $this->provider1->getBeginAuthenticationCallCount());
+        $this->assertSame($context, $this->provider1->getLastContext());
+        $this->assertSame(1, $this->provider2->getBeginAuthenticationCallCount());
+        $this->assertSame($context, $this->provider2->getLastContext());
     }
 
     #[Test]