Weave Code
Otphp Laravel Package
spomky-labs/otphp
A PHP library for generating one-time passwords using the HOTP (RFC 4226) and TOTP (RFC 6238) algorithms, compatible with Google Authenticator and other apps. Generate, verify, and manage OTP secrets easily in your PHP projects.
TOTP and HOTP one-time passwords.
Frequently asked questions about Otphp
- When should I use spomky-labs/otphp in a Laravel app, and how do I install it?
- Use spomky-labs/otphp when you need to compute RFC 6238 TOTP or RFC 4226 HOTP codes inside your own Laravel two-factor feature. Install it with composer require spomky-labs/otphp:^11.4.3; it is framework-agnostic and does not need a Laravel service provider. Confirm your Laravel and PHP 8.x constraints with composer why-not before merging, and pin at least 11.4.3 because earlier versions contain fixed security advisories.
- Does spomky-labs/otphp handle the full Laravel two-factor authentication flow?
- No. otphp only generates and verifies one-time password codes; it has no user model, secret storage, enrollment UI, recovery codes, rate limiting, or replay protection. In Laravel you must own those policies in your application service, migrations, controllers, middleware, and jobs. Treat the package as an HMAC arithmetic dependency, not a complete 2FA product.
- How do I generate a TOTP secret and provisioning URI for Google Authenticator in Laravel?
- Create a TOTP with TOTP::generate(), set the issuer and account label, then call getProvisioningUri() and render it as a QR code for Google Authenticator or FreeOTP. Store the returned secret encrypted in a nullable users column such as two_factor_secret; use TOTP::createFromSecret() when loading an existing secret later. Keep issuer and label consistent so authenticator entries remain recognizable.
- How do I verify a TOTP code with a window or leeway in Laravel?
- Pass the submitted code to verify() along with the allowed window or leeway, typically plus or minus one 30-second period. Configure digits, algorithm, period, and leeway centrally in config/two_factor.php because Google Authenticator compatibility is narrow. Verification must be one part of your login flow, followed by throttling, audit logging, and replay prevention.
- Should I use spomky-labs/otphp or Laravel Fortify for two-factor authentication?
- Laravel Fortify already provides enrollment, confirmation, recovery codes, and a login challenge, so evaluate it before adopting otphp. Choose otphp when you need HOTP, custom issuer and label semantics, provisioning-URI import from third-party authenticators, or a framework-agnostic core outside Fortify. If passkeys or WebAuthn are likely, build TOTP as one strategy behind an interface rather than hardcoding it into login.
- How should I store OTP secrets and recovery codes in Laravel?
- Store OTP secrets in an encrypted nullable column using Laravel's encrypted cast, or in an external KMS if your threat model requires it. Never log the secret or provisioning URI, and keep recovery codes in a separate table with hashes and used_at timestamps. Plan rotation and re-enrollment because a leaked TOTP secret is equivalent to a compromised second factor.
- What security issues were fixed in otphp 11.4.3, and which version should I require?
- Two medium-severity advisories were fixed in 11.4.3: unbounded digits could cause DivisionByZeroError, and hostile otpauth:// URIs could exploit property mass assignment through Factory::loadFromProvisioningUri(). Require ^11.4.3 or a later safe minor and reject any constraint below it in review. Also read release notes for breaking changes across v9, v10, and v11 rather than relying only on the changelog.
- Can spomky-labs/otphp import an otpauth:// URI from another authenticator app?
- Yes. Factory::loadFromProvisioningUri() can parse an otpauth:// URI for import flows, but you must treat that input as hostile and validate it before use. Use 11.4.3 or later because earlier Factory parsing was affected by the mass-assignment advisory. After import, store the extracted secret encrypted and confirm the account label with the user.
- How do I test TOTP verification in Laravel without waiting for time to pass?
- Inject a PSR-20 clock or wrap the library behind a TotpService that accepts a fixed timestamp, so tests can call at() or now() deterministically. In Laravel, Carbon::setTestNow() can drive your wrapper without sleeping for a 30-second period. Test valid codes, expired codes, boundary windows, replay attempts, and throttling behavior.
- Is spomky-labs/otphp actively maintained, and what is the bus-factor risk?
- otphp is heavily single-maintainer but responsive and sponsorship-funded, so treat the bus factor as a real risk. The RFCs are deterministic and the library is small, which makes forking or replacing it with pragmarx/google2fa or Laravel Fortify's built-in 2FA feasible at modest cost. Pin a minor range, monitor advisories, and keep your integration behind an interface so replacement is not a rewrite.
Weaver
How can I help you explore Laravel packages today?