TotpService
in package
TOTP (Time-based One-Time Password) Service.
Implements RFC 6238 TOTP and RFC 4226 HOTP for two-factor authentication. Compatible with Google Authenticator, Authy, Microsoft Authenticator, etc.
Uses PHP built-in HMAC-SHA1 — no external library required.
Storage: user_totp_secret table (user_id, secret, verified, created_at).
The secret is stored encrypted if EncryptionService is available.
Table of Contents
Methods
- confirmEnrollment() : bool
- Mark the user's TOTP secret as verified (after they confirm with a valid code).
- generateCode() : string
- Generate the current TOTP code.
- generateEmailCode() : string
- Generate and store a one-time email verification code.
- generateSecret() : string
- Generate a new TOTP secret for a user.
- getProvisioningUri() : string
- Generate the otpauth:// provisioning URI for authenticator apps.
- getQrCodeUrl() : string
- Generate a QR code as a data URI (SVG) for the provisioning URI.
- getSecret() : string|null
- Get the stored secret for a user.
- hasPendingSetup() : bool
- Check if a user has a pending (unverified) TOTP setup.
- isEnrolled() : bool
- Check if a user has TOTP set up and verified.
- removeEnrollment() : bool
- Remove TOTP enrollment for a user (admin action).
- verifyCode() : bool
- Verify a TOTP code against a user's stored secret.
- verifyCodeWithSecret() : bool
- Verify a TOTP code against a known secret.
- verifyEmailCode() : bool
- Verify an email fallback code.
Methods
confirmEnrollment()
Mark the user's TOTP secret as verified (after they confirm with a valid code).
public
static confirmEnrollment(int $userId) : bool
Parameters
- $userId : int
Return values
boolgenerateCode()
Generate the current TOTP code.
public
static generateCode(string $secret) : string
Parameters
- $secret : string
-
Base32-encoded secret
Return values
string —6-digit code (zero-padded)
generateEmailCode()
Generate and store a one-time email verification code.
public
static generateEmailCode(int $userId) : string
Parameters
- $userId : int
-
The user ID
Return values
string —6-digit code
generateSecret()
Generate a new TOTP secret for a user.
public
static generateSecret(int $userId) : string
Parameters
- $userId : int
-
The user ID
Return values
string —The base32-encoded secret (display to user for manual entry)
getProvisioningUri()
Generate the otpauth:// provisioning URI for authenticator apps.
public
static getProvisioningUri(string $secret, string $accountName) : string
Parameters
- $secret : string
-
Base32 secret
- $accountName : string
-
User's email or display name
Return values
string —otpauth://totp/... URI
getQrCodeUrl()
Generate a QR code as a data URI (SVG) for the provisioning URI.
public
static getQrCodeUrl(string $uri) : string
Uses a simple inline SVG QR code generator — no external dependencies. Falls back to a Google Charts URL if SVG generation is not possible.
Parameters
- $uri : string
-
The otpauth:// URI
Return values
string —URL for QR code image (data: URI or Google Charts URL)
getSecret()
Get the stored secret for a user.
public
static getSecret(int $userId) : string|null
Parameters
- $userId : int
Return values
string|null —The base32 secret, or null if not enrolled
hasPendingSetup()
Check if a user has a pending (unverified) TOTP setup.
public
static hasPendingSetup(int $userId) : bool
Parameters
- $userId : int
Return values
boolisEnrolled()
Check if a user has TOTP set up and verified.
public
static isEnrolled(int $userId) : bool
Parameters
- $userId : int
Return values
boolremoveEnrollment()
Remove TOTP enrollment for a user (admin action).
public
static removeEnrollment(int $userId) : bool
Parameters
- $userId : int
Return values
boolverifyCode()
Verify a TOTP code against a user's stored secret.
public
static verifyCode(int $userId, string $code) : bool
Allows ±1 time period drift to handle clock skew between the server and the user's authenticator app.
Parameters
- $userId : int
-
The user ID
- $code : string
-
The 6-digit code to verify
Return values
bool —True if the code is valid
verifyCodeWithSecret()
Verify a TOTP code against a known secret.
public
static verifyCodeWithSecret(string $secret, string $code) : bool
Parameters
- $secret : string
-
Base32-encoded secret
- $code : string
-
The code to verify
Return values
bool —True if valid
verifyEmailCode()
Verify an email fallback code.
public
static verifyEmailCode(int $userId, string $code) : bool
Parameters
- $userId : int
- $code : string