remotemerge/totp-php

Lightweight, fast, and secure TOTP (2FA) authentication library for PHP — battle tested, dependency free, and ready for enterprise integration.

v1.1.3 2025-11-03 16:16 UTC

Requires

• php: ^8.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89.1
• phpunit/phpunit: ^10.5.58
• rector/rector: ^2.2.7

MIT

• Madan Sapkota

• security
• Authentication
• auth
• two-factor
• otp
• totp
• hmac
• one-time-password
• 2fa
• two-factor-authentication
• multi-factor-authentication
• php-security
• web-security
• api-security
• php-2fa
• secure-authentication
• time-based-otp

README

Table of Contents

#	Title	Description
1	Why TOTP PHP?	Ideal for secure logins, data protection, and enhanced user security.
2	Key Features	Secure secret generation, multi-algorithm support, QR codes, customization.
3	Compatibility	Works seamlessly with all major authenticator apps and RFC-compliant tools.
4	Get Started	Quick installation via Composer and simple usage examples.
5	Basic Usage	Generate secrets, TOTP codes, verify codes, and create QR code URIs.
6	Customization	Change hash algorithms, code length, and time slice duration.
7	Advanced Usage	Verify codes with discrepancy and generate QR code images.
8	Try with Docker	Test locally using Docker for quick setup.
9	Try without Docker	Use PHP's built-in server for lightweight local testing.
10	Getting Help	Report bugs, get integration help, or collaborate on projects.
11	Contribution	Follow coding standards, test code, and submit pull requests.
12	Screenshots	Visual demo of the library in action.

Why Choose TOTP PHP?

TOTP PHP is a versatile, secure, and reliable TOTP library for PHP that provides easy 2FA integration. This developer-friendly, lightweight, and secure library offers simplicity, performance, and customization for secure login systems, data protection, and enhanced user security. TOTP PHP ensures robust protection with ease of use and high performance, designed for modern PHP developers.

Key Features

✅ Secure Secret Generation Generates cryptographically secure secret keys for TOTP, ensuring maximum security.

✅ Multi Algorithm Support Supports SHA1, SHA256, and SHA512 for HMAC hashing, providing flexibility and compatibility with all major authenticator apps.

✅ QR Code Integration Generates QR codes for seamless setup in authenticator apps like Google Authenticator, Microsoft Authenticator, Authy, and more.

✅ Customizable Code Length Generates TOTP codes with 6 or 8 digits, configurable based on application requirements.

✅ Time Slice Configuration Configurable time slice duration (e.g., 30 or 60 seconds) to match security requirements.

✅ Discrepancy Verification Allows time slice discrepancy when verifying TOTP codes, ensuring a smooth user experience. This is especially useful for handling clock drifts.

✅ Easy Verification Verifies TOTP codes with a simple and intuitive API, making integration straightforward.

✅ Lightweight and Fast Built for performance, TOTP PHP is lightweight and optimized for speed, ensuring minimal overhead.

✅ Developer Friendly Designed with developers in mind, TOTP PHP is easy to use, well-documented, and fully tested.

Compatibility

TOTP PHP is built to universal standards and works seamlessly with all major authenticator applications worldwide. Whether users prefer mobile apps, desktop tools, or hardware tokens, this library ensures flawless compatibility across the entire ecosystem.

Supported Authenticator Apps

📱 Mobile Authenticators	💻 Desktop & Hardware
✅ Google Authenticator	✅ YubiKey Authenticator
✅ Microsoft Authenticator	✅ FreeOTP
✅ Authy	✅ OTP Auth (iOS)
✅ Duo Mobile	✅ Aegis Authenticator
✅ 1Password	✅ andOTP
✅ LastPass Authenticator	✅ Any RFC-compliant tool
✅ Bitwarden Authenticator

Standards Compliance

🔒 RFC-Compliant Implementation TOTP PHP fully adheres to the IETF otpauth URI specification and the Key URI Format standard, ensuring maximum interoperability with any RFC-compliant two-factor authentication tool. The library works reliably across platforms, devices, and authenticator applications without vendor lock-in.

Get Started in Minutes

Adding TOTP PHP to a project is quick and easy. The library requires PHP 8.1 or higher.

Installation

Install the library via Composer:

composer require remotemerge/totp-php

Basic Usage

Generate a Secret Key

use RemoteMerge\Totp\TotpFactory;

// Create a new TOTP instance
$totp = TotpFactory::create();

// Generate a new secret key for the user
$secret = $totp->generateSecret();

// Output the secret key
echo "Generated Secret Key: $secret\n";

Output:

Generated Secret Key: JBSWY3DPEHPK3PXP

Generate a TOTP Code

use RemoteMerge\Totp\TotpFactory;

// Create a new TOTP instance
$totp = TotpFactory::create();

// Example secret key
$secret = 'JBSWY3DPEHPK3PXP';

// Generate a TOTP code
$code = $totp->getCode($secret);

echo "Generated TOTP Code: $code\n";

Output:

Generated TOTP Code: 123456

Verify a TOTP Code

use RemoteMerge\Totp\TotpFactory;

// Create a new TOTP instance
$totp = TotpFactory::create();

// Example secret key and code
$secret = 'JBSWY3DPEHPK3PXP';
$code = '123456';

// Verify the code
$isValid = $totp->verifyCode($secret, $code);

echo $isValid ? "✅ Code is valid!\n" : "❌ Code is invalid!\n";

Output:

✅ Code is valid!

Generate a QR Code URI

use RemoteMerge\Totp\TotpFactory;

// Create a new TOTP instance
$totp = TotpFactory::create();

// Example secret key and user information
$secret = 'JBSWY3DPEHPK3PXP';
$uri = $totp->generateUri($secret, '[e-mail]', 'YourApp');

echo "QR Code URI: $uri\n";

Output:

QR Code URI: otpauth://totp/YourApp:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp&algorithm=SHA1&digits=6&period=30

Customization Options

Change the Hash Algorithm

By default, TOTP PHP uses SHA1. The algorithm can be configured to use SHA256 or SHA512:

use RemoteMerge\Totp\TotpFactory;

$totp = TotpFactory::create();

// Configure the algorithm
$totp->configure(['algorithm' => 'SHA256']);

$secret = $totp->generateSecret();
$code = $totp->getCode($secret);

echo "Generated TOTP Code (SHA256): $code\n";

Change the Code Length

By default, TOTP PHP generates 6-digit codes. The length can be configured to 8 digits:

use RemoteMerge\Totp\TotpFactory;

$totp = TotpFactory::create();

// Configure the code length
$totp->configure(['digits' => 8]);

$secret = $totp->generateSecret();
$code = $totp->getCode($secret);

echo "Generated 8-Digit TOTP Code: $code\n";

Change the Time Slice Duration

By default, TOTP PHP uses a 30-second time slice. The duration can be configured to 60 seconds:

use RemoteMerge\Totp\TotpFactory;

$totp = TotpFactory::create();

// Configure the time slice duration
$totp->configure(['period' => 60]);

$secret = $totp->generateSecret();
$code = $totp->getCode($secret);

echo "Generated TOTP Code (60-second period): $code\n";

Advanced Usage

Verify Code with Discrepancy

Handle clock drift by allowing a discrepancy of ±1 time slice:

use RemoteMerge\Totp\TotpFactory;

$totp = TotpFactory::create();

$secret = 'JBSWY3DPEHPK3PXP';
$code = '123456';

// Allow discrepancy of 1 time slice
$isValid = $totp->verifyCode($secret, $code, 1);

echo $isValid ? "✅ Code is valid!\n" : "❌ Code is invalid!\n";

Generate a QR Code Image

Use the QR code URI to generate a QR code image:

use RemoteMerge\Totp\TotpFactory;

$totp = TotpFactory::create();

$secret = 'JBSWY3DPEHPK3PXP';
$uri = $totp->generateUri($secret, '[e-mail]', 'YourApp');

$qrCodeUrl = "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=" . urlencode($uri);

echo "QR Code Image URL: $qrCodeUrl\n";

Try with Docker

Test the TOTP PHP library locally using Docker. This method automatically sets up the environment with all dependencies. Follow these steps:

1. Clone the repository:

   git clone [e-mail]:remotemerge/totp-php.git
   cd totp-php

2. Start the Docker container:

   bash start-docker.sh

3. Access the application at http://localhost:8080.

4. (Optional) Access the container shell for development:

   bash pkg-cli.sh

Try with PHP

For a lightweight setup, use PHP's built-in server. This method is ideal for quick local testing and doesn't require Docker. Follow these steps:

1. Clone the repository:

   git clone [e-mail]:remotemerge/totp-php.git
   cd totp-php

2. Install dependencies using Composer:

   composer install

3. Start the PHP built-in server:

   php -S localhost:8080 -t public

4. Access the application at http://localhost:8080.

Getting Help

Bugs and feature requests are tracked using GitHub issues and prioritized to ensure the library remains reliable and up to date.

• Bug Reports Issues can be reported by opening an issue on GitHub. All issues are addressed diligently to maintain the library's quality.

• Integration Assistance For assistance with integration or questions about features, please open a GitHub issue or discussion.

Contribution

Contributions from the Open Source community are highly valued and appreciated. To ensure a smooth and efficient process, contributors should adhere to the following guidelines:

• Coding Standards: Code must adhere to PER Coding Style 3.0 standards.
• Testing: All submitted code must pass relevant tests to maintain the library's reliability.
• Documentation: Proper documentation and clean code practices are essential for maintainability.
• Pull Requests: Pull requests should be made to the main branch.

All contributions are reviewed and appreciated.

Screenshots