PHP 8.2+

Author: codemasher

.github/workflows/ci.yml

@@ -38,17 +38,14 @@ jobs:
       fail-fast: true
       matrix:
         php-version:
-          - "7.4"
-          - "8.0"
-          - "8.1"
           - "8.2"
           - "8.3"
           - "8.4"
-#          - "8.5"
+          - "8.5"
 
     steps:
       - name: "Checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: "Install PHP"
         uses: shivammathur/setup-php@v2
@@ -83,17 +80,14 @@ jobs:
           - ubuntu-latest
           - windows-latest
         php-version:
-          - "7.4"
-          - "8.0"
-          - "8.1"
           - "8.2"
           - "8.3"
           - "8.4"
           - "8.5"
 
     steps:
       - name: "Checkout"
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: "Install PHP with extensions"
         uses: shivammathur/setup-php@v2

.phan/config.php

@@ -13,7 +13,7 @@
 	// that functions removed in php 7.0 exist.
 	// (See `backward_compatibility_checks` for additional options)
 	'target_php_version'              => null,
-	'minimum_target_php_version'      => '7.4',
+	'minimum_target_php_version'      => '8.2',
 
 	// A list of directories that should be parsed for class and
 	// method information. After excluding the directories

README.md

@@ -21,7 +21,7 @@ An authenticator ([chillerlan/php-authenticator](https://github.com/chillerlan/p
 
 ## Requirements
 
-- PHP 7.4+
+- PHP 8.2+
   - [`ext-mbstring`](https://www.php.net/manual/book.mbstring.php)
   - optional:
     - [`ext-gd`](https://www.php.net/manual/book.image) for `QRGdImage` based output
@@ -35,27 +35,27 @@ You can find the documentation of the bundled libraries in their respective repo
 
 - [chillerlan/php-authenticator](https://github.com/chillerlan/php-authenticator)
 - [chillerlan/php-qrcode](https://github.com/chillerlan/php-qrcode)
-  - User manual: https://php-qrcode.readthedocs.io/
+  - User manual: https://php-qrcode.readthedocs.io/en/v6.0.x/
   - API documentation: https://chillerlan.github.io/php-qrcode/
 - [chillerlan/php-settings-container](https://github.com/chillerlan/php-settings-container)
 
 ### User Guide
 
 #### Invocation
 
-Fetch the settings from e.g. a framework config and [invoke the `TwoFactorQRCodeOptions` instance](https://php-qrcode.readthedocs.io/en/v5.0.x/Usage/Advanced-usage.html#configuration-via-qroptions) with it.
-Please note that this object combines the settings for [`AuthenticatorOptions`](https://github.com/chillerlan/php-authenticator?tab=readme-ov-file#authenticatoroptions) and [`QROptions`](https://php-qrcode.readthedocs.io/en/v5.0.x/Usage/Configuration-settings.html).
+Fetch the settings from e.g. a framework config and [invoke the `TwoFactorQRCodeOptions` instance](https://php-qrcode.readthedocs.io/en/v6.0.x/Usage/Advanced-usage.html#configuration-via-qroptions) with it.
+Please note that this object combines the settings for [`AuthenticatorOptions`](https://github.com/chillerlan/php-authenticator?tab=readme-ov-file#authenticatoroptions) and [`QROptions`](https://php-qrcode.readthedocs.io/en/v6.0.x/Usage/Configuration-settings.html).
+Alternatively, you can just pass an `iterable` of options to the `TwoFactorQRCode` constructor.
 
 ```php
-use chillerlan\TwoFactorQRCode\{TwoFactorQRCode, TwoFactorQRCodeOptions};
+use chillerlan\TwoFactorQRCode\TwoFactorQRCode;
 
 $options = [
 	'secret_length' => 128,
 	'adjacent'      => 2,
 ];
 
-$twoFactorQRCodeOptions = new TwoFactorQRCodeOptions($options);
-$twoFactorQRCode        = new TwoFactorQRCode($twoFactorQRCodeOptions);
+$twoFactorQRCode = new TwoFactorQRCode($options);
 ```
 
 #### User registration
@@ -100,7 +100,6 @@ The user has lost access to their authenticator, send them to a form separate fr
 - Verify the given backup OTP against the stored counter value.
 - After verification, increase the counter, create a new backup code and save the new counter value.
 - Present the new backup code to the user and make them triple check that they have carefully saved it.
-- Redirect the user to wherever they can manage their 2FA settings and retrieve their secret once again.
 
 ```php
 $twoFactorQRCode->setSecret($userSecret);
@@ -114,6 +113,15 @@ if($twoFactorQRCode->verifyBackupCode($backupOTP, $counterValue)){
 }
 ```
 
+Redirect the user to wherever they can manage their 2FA settings and retrieve their secret once again:
+
+```php
+$twoFactorQRCode->setSecret($userSecret);
+
+$currentBackup = $twoFactorQRCode->createBackupCode($currentCounterValue);
+$qrcode        = $twoFactorQRCode->getQRCode('label', 'issuer');
+```
+
 #### Validating an e-mail address
 
 The previous flow can also be used for other tasks, such as e-mail verification:
@@ -158,18 +166,18 @@ However, some of [the top used libraries on packagist](https://packagist.org/sea
 
 The class is not final and you're free to extend it to add/change functionality to your liking.
 
-| method                                                          | return   | description                                                                                                   |
-|-----------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------|
-| `__construct(SettingsContainerInterface\|null $options = null)` | -        |                                                                                                               |
-| `createSecret(int\|null $length = null)`                        | `string` | Creates a cryptograpically secure random secret and returns it as Base32 encoded string                       |
-| `setSecret(string $encodedSecret)`                              | `static` | Sets a secret phrase from an encoded representation                                                           |
-| `getSecret()`                                                   | `string` | Returns an encoded representation of the current secret phrase                                                |
-| `setRawSecret(string $rawSecret)`                               | `static` | Sets a secret phrase from a raw binary representation                                                         |
-| `getRawSecret()`                                                | `string` | Returns the raw representation of the current secret phrase                                                   |
-| `verifyOTP(string $otp, int\|null $timestamp = null)`           | `bool`   | Verifies a one-time password (TOTP) with an optional unix timestamp                                           |
-| `createBackupCode(int $counter)`                                | `string` | Creates a counter-based one-time password (HOTP) from the given counter value                                 |
-| `verifyBackupCode(string $otp, int $counter)`                   | `bool`   | Verifies a counter-based backup code (HOTP) against the given counter value                                   |
-| `getQRCode(string $label, string $issuer)`                      | `string` | Creates a QR Code for use with a mobile authenticator application (TOTP) with the given label and issuer name |
+| method                                                                                                             | return   | description                                                                                                   |
+|--------------------------------------------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------|
+| `__construct(SettingsContainerInterface\|TwoFactorQRCodeOptions \|iterable $options = new TwoFactorQRCodeOptions)` | -        |                                                                                                               |
+| `createSecret(int\|null $length = null)`                                                                           | `string` | Creates a cryptograpically secure random secret and returns it as Base32 encoded string                       |
+| `setSecret(string $encodedSecret)`                                                                                 | `static` | Sets a secret phrase from an encoded representation                                                           |
+| `getSecret()`                                                                                                      | `string` | Returns an encoded representation of the current secret phrase                                                |
+| `setRawSecret(string $rawSecret)`                                                                                  | `static` | Sets a secret phrase from a raw binary representation                                                         |
+| `getRawSecret()`                                                                                                   | `string` | Returns the raw representation of the current secret phrase                                                   |
+| `verifyOTP(string $otp, int\|null $timestamp = null)`                                                              | `bool`   | Verifies a one-time password (TOTP) with an optional unix timestamp                                           |
+| `createBackupCode(int $counter)`                                                                                   | `string` | Creates a counter-based one-time password (HOTP) from the given counter value                                 |
+| `verifyBackupCode(string $otp, int $counter)`                                                                      | `bool`   | Verifies a counter-based backup code (HOTP) against the given counter value                                   |
+| `getQRCode(string $label, string $issuer)`                                                                         | `string` | Creates a QR Code for use with a mobile authenticator application (TOTP) with the given label and issuer name |
 
 
 ## Anti clanker policy

composer.json

@@ -33,15 +33,15 @@
 	"minimum-stability": "stable",
 	"prefer-stable": true,
 	"require": {
-		"php": "^7.4 || ^8.0",
-		"chillerlan/php-authenticator": "^4.5.0",
-		"chillerlan/php-qrcode": "^5.0.5",
-		"chillerlan/php-settings-container": "^2.1.6"
+		"php": "^8.2",
+		"chillerlan/php-authenticator": "^5.4.0",
+		"chillerlan/php-qrcode": "^6.0",
+		"chillerlan/php-settings-container": "^3.2.1"
 	},
 	"require-dev": {
-		"phan/phan": "^5.5.2",
+		"phan/phan": "^6.0.2",
 		"phpmd/phpmd": "^2.15",
-		"phpunit/phpunit": "^9.6",
+		"phpunit/phpunit": "^11.5",
 		"slevomat/coding-standard": "^8.28",
 		"squizlabs/php_codesniffer": "^4.0"
 	},

examples/example.php

@@ -10,7 +10,6 @@
 declare(strict_types=1);
 
 use chillerlan\TwoFactorQRCode\TwoFactorQRCode;
-use chillerlan\TwoFactorQRCode\TwoFactorQRCodeOptions;
 
 require_once __DIR__.'/../vendor/autoload.php';
 
@@ -24,9 +23,8 @@
 	'adjacent'      => 2,
 ];
 
-// invoke settings and TwoFactorQRCode instance
-$twoFactorQRCodeOptions = new TwoFactorQRCodeOptions($options);
-$twoFactorQRCode        = new TwoFactorQRCode($twoFactorQRCodeOptions);
+// invoke  TwoFactorQRCode instance
+$twoFactorQRCode = new TwoFactorQRCode($options);
 
 
 /**

phpcs.xml.dist

@@ -111,7 +111,7 @@
 
 	<rule ref="SlevomatCodingStandard.TypeHints.DNFTypeHintFormat">
 		<properties>
-			<property name="shortNullable" value="true"/>
+			<property name="shortNullable" value="false"/>
 			<property name="nullPosition" value="last"/>
 		</properties>
 	</rule>

phpunit.xml.dist

@@ -1,20 +1,21 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version="1.0"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
          bootstrap="vendor/autoload.php"
-         cacheResultFile=".build/phpunit.result.cache"
+         cacheDirectory=".build/phpunit-cache"
          colors="true"
-         verbose="true"
 >
 	<testsuites>
-		<testsuite name="php-authenticator test suite">
+		<testsuite name="chillerlan test suite">
 			<directory>tests</directory>
 		</testsuite>
 	</testsuites>
-	<coverage processUncoveredFiles="true">
+	<source>
 		<include>
-			<directory suffix=".php">src</directory>
+			<directory>src</directory>
 		</include>
+	</source>
+	<coverage>
 		<report>
 			<clover outputFile=".build/coverage/clover.xml"/>
 			<xml outputDirectory=".build/coverage/coverage-xml"/>

src/TwoFactorQRCode.php

@@ -14,24 +14,30 @@
 use chillerlan\QRCode\QRCode;
 use chillerlan\Authenticator\Authenticators\{HOTP, TOTP};
 use chillerlan\Settings\SettingsContainerInterface;
+use SensitiveParameter;
+use function is_iterable;
 
 class TwoFactorQRCode{
 
 	protected SettingsContainerInterface $options;
 	protected HOTP                       $hotp;
 	protected TOTP                       $totp;
 
-	/**
-	 * @param \chillerlan\Settings\SettingsContainerInterface|\chillerlan\TwoFactorQRCode\TwoFactorQRCodeOptions|null $options
-	 */
-	public function __construct(?SettingsContainerInterface $options = null){
-		$this->options = ($options ?? new TwoFactorQRCodeOptions);
+	public function __construct(
+		SettingsContainerInterface|TwoFactorQRCodeOptions|iterable $options = new TwoFactorQRCodeOptions,
+	){
+
+		if(is_iterable($options)){
+			$options = new TwoFactorQRCodeOptions($options);
+		}
+
+		$this->options = $options;
 		$this->hotp    = new HOTP($this->options);
 		$this->totp    = new TOTP($this->options);
 	}
 
 	/**
-	 * Creates a cryptograpically secure random secret and returns it as Base32 encoded string.
+	 * Creates a cryptographically secure random secret and returns it as Base32 encoded string.
 	 *
 	 * Note: The secret length is the length of the raw binary string,
 	 *       the Base32 encoded string is considerably longer (~60%).
@@ -40,7 +46,7 @@ public function __construct(?SettingsContainerInterface $options = null){
 	 * @see \random_bytes()
 	 * @see \ParagonIE\ConstantTime\Base32
 	 */
-	public function createSecret(?int $length = null):string{
+	public function createSecret(int|null $length = null):string{
 		$secret = $this->hotp->createSecret($length);
 
 		$this->totp->setSecret($secret);
@@ -51,7 +57,7 @@ public function createSecret(?int $length = null):string{
 	/**
 	 * Sets a secret phrase from an encoded representation
 	 */
-	public function setSecret(string $encodedSecret):self{
+	public function setSecret(#[SensitiveParameter] string $encodedSecret):static{
 		$this->hotp->setSecret($encodedSecret);
 		$this->totp->setSecret($encodedSecret);
 
@@ -68,7 +74,7 @@ public function getSecret():string{
 	/**
 	 * Sets a secret phrase from a raw binary representation
 	 */
-	public function setRawSecret(string $rawSecret):self{
+	public function setRawSecret(#[SensitiveParameter] string $rawSecret):static{
 		$this->hotp->setRawSecret($rawSecret);
 		$this->totp->setRawSecret($rawSecret);
 
@@ -87,7 +93,7 @@ public function getRawSecret():string{
 	 *
 	 * @see \chillerlan\Authenticator\Authenticators\TOTP
 	 */
-	public function verifyOTP(string $otp, ?int $timestamp = null):bool{
+	public function verifyOTP(string $otp, int|null $timestamp = null):bool{
 		return $this->totp->verify($otp, $timestamp);
 	}
 

src/TwoFactorQRCodeOptions.php

@@ -12,9 +12,10 @@
 namespace chillerlan\TwoFactorQRCode;
 
 use chillerlan\Authenticator\AuthenticatorOptionsTrait;
+use chillerlan\QRCode\QRCodeReaderOptionsTrait;
 use chillerlan\QRCode\QROptionsTrait;
 use chillerlan\Settings\SettingsContainerAbstract;
 
 class TwoFactorQRCodeOptions extends SettingsContainerAbstract{
-	use AuthenticatorOptionsTrait, QROptionsTrait;
+	use AuthenticatorOptionsTrait, QROptionsTrait, QRCodeReaderOptionsTrait;
 }

tests/TwoFactorQRCodeTest.php

@@ -14,10 +14,11 @@
 use chillerlan\Authenticator\Common\Base32;
 use chillerlan\QRCode\Common\GDLuminanceSource;
 use chillerlan\QRCode\Decoder\Decoder;
-use chillerlan\QRCode\Output\QROutputInterface;
+use chillerlan\QRCode\Output\QRGdImagePNG;
 use chillerlan\TwoFactorQRCode\TwoFactorQRCode;
 use chillerlan\TwoFactorQRCode\TwoFactorQRCodeOptions;
 use Generator;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use function date;
 use function is_int;
@@ -94,9 +95,7 @@ public static function totpVectors():Generator{
 		}
 	}
 
-	/**
-	 * @dataProvider totpVectors
-	 */
+	#[DataProvider('totpVectors')]
 	public function testVerifyOTP(int $timestamp, string $totp):void{
 		$this->twoFactorQRCodeOptions->digits = 8;
 
@@ -109,24 +108,20 @@ public static function hotpVectors():Generator{
 		}
 	}
 
-	/**
-	 * @dataProvider hotpVectors
-	 */
+	#[DataProvider('hotpVectors')]
 	public function testCreateBackupCode(int $counter, string $hotp):void{
 		$this::assertSame($hotp, $this->twoFactorQRCode->createBackupCode($counter));
 	}
 
-	/**
-	 * @dataProvider hotpVectors
-	 */
+	#[DataProvider('hotpVectors')]
 	public function testVerifyBackupCode(int $counter, string $hotp):void{
 		$this::assertTrue($this->twoFactorQRCode->verifyBackupCode($hotp, $counter));
 	}
 
 	public function testGetQRCode():void{
 		/** @phan-suppress-next-line PhanDeprecatedClassConstant */
-		$this->twoFactorQRCodeOptions->outputType   = QROutputInterface::GDIMAGE_PNG;
-		$this->twoFactorQRCodeOptions->outputBase64 = false;
+		$this->twoFactorQRCodeOptions->outputInterface = QRGdImagePNG::class;
+		$this->twoFactorQRCodeOptions->outputBase64    = false;
 
 		$qrcode = $this->twoFactorQRCode->getQRCode('testLabel', 'testIssuer');
 		$result = (new Decoder)->decode(GDLuminanceSource::fromBlob($qrcode));