Weave Code
Two Factor For Laravel Laravel Package
roundly-consulting/two-factor-for-laravel
A Laravel package for adding two-factor authentication with TOTP, QR-code setup, recovery codes, and middleware protection. Simple configuration and Blade-ready flows help secure user accounts without building 2FA from scratch.
Native RFC 6238 TOTP two-factor authentication for Laravel — encrypted secrets, single-use recovery codes and replay protection with zero third-party crypto.
Frequently asked questions about Two Factor For Laravel
- How do I install roundly-consulting/two-factor-for-laravel in a Laravel app?
- Require it with composer require roundly-consulting/two-factor-for-laravel, then publish the package configuration and add the two-factor columns to your users table — the package registers twoFactorColumns() and dropTwoFactorColumns() blueprint macros so you do not hand-write the schema. Run php artisan migrate and wire the provided middleware and Blade views into your login flow. The 1.1.6 release is a drop-in composer update with no new database migration and no required config publish.
- Which Laravel and PHP versions does this two-factor package support?
- It targets Laravel 9, 10 and 11 applications running PHP 8.1 or newer. The runtime contract has not changed across recent patch releases, so upgrading from earlier 1.x versions is a straight composer update. If you maintain older Laravel 8 projects, check the composer.json constraints on the repository, since those fall outside the documented support window.
- How are TOTP secrets stored — are they encrypted and does it need third-party crypto?
- TOTP secrets are stored encrypted using Laravel's own encrypter, so the package does not pull in an external crypto library to protect them. The TOTP algorithm itself is implemented with PHP's built-in primitives, which keeps your dependency tree small and avoids PECL extensions in your deployment image. Practically, it means secrets are only readable with your application key, so treat APP_KEY rotation as a 2FA-affecting operation.
- Are the recovery codes single-use?
- Recovery codes are issued at enrolment and each one is consumed on first successful use, so a leaked or intercepted code cannot be replayed later. That gives users a fallback when they lose their authenticator device without weakening the second factor. Surface the codes to the user once at setup, because they cannot be retrieved again afterwards.
- What does replay protection mean for TOTP in this package?
- Standard TOTP accepts any code inside a validity window, so an attacker who intercepts a code can usually reuse it within that window. This package tracks used codes or time steps and rejects a second submission of the same value. That closes the classic intercept-and-replay gap without changing anything on the authenticator app side.
- How do I set up QR-code enrolment for Google Authenticator or Authy?
- The package provides QR-code enrolment that encodes a standard otpauth URI, so users can scan it with Google Authenticator, Authy, 1Password or any RFC 6238 compatible app, and it ships Blade-ready views to render the flow. You can also display the secret for manual entry when a camera is unavailable. A confirmation step verifies a submitted code before two-factor is actually switched on for the account.
- How do I protect routes with the package's two-factor middleware?
- Apply the middleware to the route groups that require a completed second-factor challenge, or globally to authenticated areas and let the package redirect users who have not confirmed yet. Because it is ordinary Laravel middleware, it composes with your existing auth, verified and throttle middleware. Keep the enrolment and challenge routes outside the protected group, otherwise users get locked out of the flow they need to complete.
- Why does PHPStan report 'Call to an undefined method Blueprint::twoFactorColumns()'?
- The blueprint macros only exist once the package's service provider boots, so static analysers that never boot it — Testbench package development, dont-discover apps, and manually registered providers — cannot see them. Version 1.1.6 adds a PHPStan extension that declares both macros, auto-loaded through phpstan/extension-installer via extra.phpstan.includes. After updating, remove any inline @phpstan-ignore comments or baseline entries for these macros, otherwise the fix stays inert and you capture none of the value.
- How do I enable the PHPStan extension without phpstan/extension-installer?
- If your project deliberately excludes phpstan/extension-installer, which some teams do because it auto-loads third-party configuration, add the package's extension.neon to the includes array of your phpstan.neon manually. The README documents the exact path and snippet to use. Then rerun the analyser and confirm the macro errors are gone; if they persist, check that a host configuration is not shadowing the include.
- How do I test two-factor authentication flows in my Laravel test suite?
- Generate a valid TOTP inside the test using the same algorithm rather than hard-coding a code, because values are time-based, and freeze or travel time with Laravel's time helpers for determinism. Replay protection means you must not reuse the same code across two assertions in a single test, so generate a fresh one per attempt. Enrolling users through a factory state or direct model setup keeps the challenge and recovery-code tests readable.
Weaver
How can I help you explore Laravel packages today?