Add migration API for readonly classes

.ci-tools/phpstan-baseline.neon

@@ -1,5 +1,41 @@
 parameters:
 	ignoreErrors:
+		-
+			rawMessage: '''
+				Call to deprecated method setIssuer() of interface OTPHP\OTPInterface:
+				Deprecated since v11.4, use {@see self::withIssuer()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/Factory.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setIssuerIncludedAsParameter() of interface OTPHP\OTPInterface:
+				Deprecated since v11.4, use {@see self::withIssuerIncludedAsParameter()} instead
+			'''
+			identifier: method.deprecated
+			count: 2
+			path: ../src/Factory.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setLabel() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withLabel()} instead
+			'''
+			identifier: method.deprecated
+			count: 2
+			path: ../src/Factory.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setParameter() of interface OTPHP\OTPInterface:
+				Deprecated since v11.4, use {@see self::withParameter()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/Factory.php
+
 		-
 			rawMessage: Control structures using switch should not be used.
 			identifier: ergebnis.noSwitch
@@ -18,6 +54,42 @@ parameters:
 			count: 1
 			path: ../src/Factory.php
 
+		-
+			rawMessage: '''
+				Call to deprecated method setCounter() of class OTPHP\HOTP:
+				Deprecated since v11.4, use {@see self::withCounter()} instead
+			'''
+			identifier: method.deprecated
+			count: 2
+			path: ../src/HOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setDigest() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withDigest()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/HOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setDigits() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withDigits()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/HOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setParameter() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withParameter()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/HOTP.php
+
 		-
 			rawMessage: Cannot cast mixed to int.
 			identifier: cast.int
@@ -90,6 +162,24 @@ parameters:
 			count: 1
 			path: ../src/HOTPInterface.php
 
+		-
+			rawMessage: @@readonly property OTPHP\OTP::$issuer_included_as_parameter is assigned outside of the constructor.
+			identifier: property.readOnlyByPhpDocAssignNotInConstructor
+			count: 2
+			path: ../src/OTP.php
+
+		-
+			rawMessage: @@readonly property OTPHP\OTP::$parameters is assigned outside of the constructor.
+			identifier: property.readOnlyByPhpDocAssignNotInConstructor
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: @@readonly property cannot have a default value.
+			identifier: property.readOnlyByPhpDocDefaultValue
+			count: 4
+			path: ../src/OTP.php
+
 		-
 			rawMessage: Binary operation "&" between mixed and 127 results in an error.
 			identifier: binaryOp.invalid
@@ -108,6 +198,24 @@ parameters:
 			count: 3
 			path: ../src/OTP.php
 
+		-
+			rawMessage: '''
+				Call to deprecated method setParameter() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withParameter()} instead
+			'''
+			identifier: method.deprecated
+			count: 6
+			path: ../src/OTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setSecret() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withSecret()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/OTP.php
+
 		-
 			rawMessage: Cannot cast mixed to int.
 			identifier: cast.int
@@ -150,6 +258,12 @@ parameters:
 			count: 1
 			path: ../src/OTP.php
 
+		-
+			rawMessage: 'Method OTPHP\OTP::generateOTP() should return non-empty-string but returns string.'
+			identifier: return.type
+			count: 1
+			path: ../src/OTP.php
+
 		-
 			rawMessage: 'Method OTPHP\OTP::generateSecret() should return non-empty-string but returns string.'
 			identifier: return.type
@@ -282,6 +396,48 @@ parameters:
 			count: 1
 			path: ../src/OTP.php
 
+		-
+			rawMessage: 'Method OTPHP\OTP::withDigest() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withDigits() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withIssuer() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withIssuerIncludedAsParameter() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withLabel() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withParameter() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
+		-
+			rawMessage: 'Method OTPHP\OTP::withSecret() is not final, but since the containing class is abstract, it should be.'
+			identifier: ergebnis.finalInAbstractClass
+			count: 1
+			path: ../src/OTP.php
+
 		-
 			rawMessage: 'Variable property access on $this(OTPHP\OTP).'
 			identifier: property.dynamicName
@@ -324,6 +480,51 @@ parameters:
 			count: 1
 			path: ../src/OTPInterface.php
 
+		-
+			rawMessage: '''
+				Call to deprecated method setDigest() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withDigest()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/TOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setDigits() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withDigits()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/TOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setEpoch() of class OTPHP\TOTP:
+				Deprecated since v11.4, use {@see self::withEpoch()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/TOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setParameter() of class OTPHP\OTP:
+				Deprecated since v11.4, use {@see self::withParameter()} instead
+			'''
+			identifier: method.deprecated
+			count: 2
+			path: ../src/TOTP.php
+
+		-
+			rawMessage: '''
+				Call to deprecated method setPeriod() of class OTPHP\TOTP:
+				Deprecated since v11.4, use {@see self::withPeriod()} instead
+			'''
+			identifier: method.deprecated
+			count: 1
+			path: ../src/TOTP.php
+
 		-
 			rawMessage: Cannot cast mixed to int.
 			identifier: cast.int

src/Factory.php

@@ -14,6 +14,8 @@
 /**
  * This class is used to load OTP object from a provisioning Uri.
  *
+ * @readonly
+ *
  * @see \OTPHP\Test\FactoryTest
  */
 final class Factory implements FactoryInterface

src/HOTP.php

@@ -8,6 +8,8 @@
 use function is_int;
 
 /**
+ * @readonly
+ *
  * @see \OTPHP\Test\HOTPTest
  */
 final class HOTP extends OTP implements HOTPInterface
@@ -87,6 +89,14 @@ public function setCounter(int $counter): void
         $this->setParameter('counter', $counter);
     }
 
+    public function withCounter(int $counter): self
+    {
+        $otp = clone $this;
+        $otp->setParameter('counter', $counter);
+
+        return $otp;
+    }
+
     /**
      * @return array<non-empty-string, callable>
      */

src/HOTPInterface.php

@@ -32,5 +32,10 @@ public static function create(
         int $digits = 6
     ): self;
 
+    /**
+     * @deprecated Deprecated since v11.4, use {@see self::withCounter()} instead
+     */
     public function setCounter(int $counter): void;
+
+    public function withCounter(int $counter): self;
 }

src/InternalClock.php

@@ -8,6 +8,8 @@
 use Psr\Clock\ClockInterface;
 
 /**
+ * @readonly
+ *
  * @internal
  */
 final class InternalClock implements ClockInterface