blackcube/totp

Totp implementation for PHP

1.0.0 2025-08-28 07:51 UTC

Requires

• php: ~8.3.0
• ext-mbstring: *

Requires (Dev)

• codeception/codeception: ~5.0
• codeception/module-asserts: ~2.0

BSD-3-Clause

• Philippe Gaultier

• security
• google authenticator
• totp
• authy
• 2fa
• 2-factor authentication

README

Installation

If you use Packagist for installing packages, then you can update your composer.json like this :

{
    "require": {
        "blackcube/totp": "*"
    }
}

Testing

To run the tests:

composer install
./vendor/bin/codecept build
./vendor/bin/codecept run

To check coverage report:

./vendor/bin/codecept run --coverage --coverage-html

Usage

Totp class allows you to generate and verify TOTP codes.

Generating TOTP Codes

use blackcube\totp\Totp;

$totp = new Totp();
$registerKey = 'JBSWY3DPEHPK3PXP'; // Base 32 encoded Key used to generate the TOTP codes
$lostPasswordKey = 'JBSWY3DPEHPK3PXA'; // Base 32 encoded Key used to generate the TOTP codes for lost password service
// Define a key for register service
$totp->setKey('register', $registerKey);
// Define a key for lost password service
$totp->setKey('lostPassword', $lostPasswordKey);

// we can force the time step (default is 30 seconds) and the window (default is 10)
$totp->setWindow(10); // Allow codes to be valid for 10 time steps
$totp->setStep(30); // Each time step is 30 seconds
// codes are valid for 5 minutes in this case
$registerTotpCode = $totp->generate('register'); // Generate a TOTP code for register service
$lostPasswordTotpCode = $totp->generate('lostPassword'); // Generate a TOTP code for lost password service

Verifying TOTP Codes

use blackcube\totp\Totp;

$totpChcecker = new Totp(
    step: 30,
    window: 10
);
$registerKey = 'JBSWY3DPEHPK3PXP'; // Base 32 encoded Key used to generate the TOTP codes
$lostPasswordKey = 'JBSWY3DPEHPK3PXA'; // Base 32 encoded Key used to generate the TOTP codes for lost password service
// Define a key for register service
$totpChcecker->setKey('register', $registerKey);
// Define a key for lost password service
$totpChcecker->setKey('lostPassword', $lostPasswordKey);

// Verify the TOTP code for register service
$isRegisterValid = $totp->verify('register', $registerTotpCode);
// Verify the TOTP code for lost password service
$isLostPasswordValid = $totp->verify('lostPassword', $lostPasswordTotpCode);

Contributing

All code contributions - including those of people having commit access - must go through a pull request and approved by a core developer before being merged. This is to ensure proper review of all the code.

Fork the project, create a feature branch , and send us a pull request.