Statamic Two Factor Laravel Package

Getting Started

1. composer require mitydigital/statamic-two-factor
2. Publish the addon's assets — at minimum the config (and any migrations/views you intend to customise) — then php artisan migrate if new user columns are added.
3. php artisan config:clear locally; in production publish config before config:cache, since the addon is entirely config-driven.
4. Enrol your own account first: CP → your user profile → the Two Factor panel → scan the QR with an authenticator app → confirm a code → download/store the recovery codes.

Where to look first

• config/two-factor.php — enforcement, issuer name, TOTP window, recovery-code count, and which factors are offered.
• vendor/mitydigital/statamic-two-factor/src — ServiceProvider (bindings, middleware registration, routes), the CP middleware that gates the Control Panel, and the challenge/setup controllers.
• The package's routes/web.php — note the challenge route name; you'll reference it in redirects and tests.
• The user blueprint/fieldset the addon injects — that's what renders the Two Factor section on the user publish form.

First use case: enrol one super admin, verify a full logout → login → challenge → recovery-code round trip in a second browser, then turn on enforcement for editors. Don't invert that order.

Implementation Patterns

• Opt-in vs. enforced. The config handles the global switch; for per-role enforcement, put your own check in a listener or a thin middleware rather than forking the addon. Keep that decision in one class so it survives upgrades.
• Backfilling existing users. Users created before install (or imported) won't have 2FA state. Decide between a migration/command that sets the flag versus a "must enrol on next login" nag — the latter is friendlier and avoids a support spike.
• Programmatic management. Whatever API the addon exposes for enabling/disabling a user (facade, user relation, or artisan command), wrap it in your own small service. Your seeders and admin tooling then only depend on your class when the package API shifts.
• Testing. Statamic::actingAs($user) will now hit the challenge middleware. Add a test helper that either uses a factory state with 2FA disabled or marks the session as verified, and use it in every existing CP feature test — otherwise a patch bump turns your suite red.
• Email factor. If you're using the email driver, verify mail delivery in local/staging before enforcing, and check code expiry against your queue latency.
• Audit trail. Hook the addon's enable/disable/verify events into your activity log. Cheap to add, and it's usually the first thing compliance asks for.
• Custom CP routes. If you add your own authenticated Control Panel pages, apply the same middleware group the addon uses, or they'll be reachable pre-challenge.
• Recovery codes. Treat them as a first-class onboarding step (print/download), not a footnote — they're the only self-service escape hatch.
• Version pinning. ^2.7 and read the changelog on each bump; 2.7.3 is a patch and is safe to take.

Gotchas and Tips

• Lockout risk is real. Test with a second session and a second browser before flipping enforcement. Confirm the CLI escape hatch in your installed version (an artisan reset command or a tinker one-liner that clears the user's 2FA state) and write it into a runbook.
• Session dependency. Challenge state lives in the session. SESSION_DRIVER=array, cookie-only setups, or multiple app servers without a shared session store will produce confusing "challenge loops".
• TOTP clock drift. Valid codes failing is almost always server time. Check NTP, then widen the verification window in config as a stopgap.
• 2.7.3 specifics. The cleanup path now removes the stored value instead of setting it. The login flow behaves the same, but any code of yours that reads that column or session key directly must handle "missing or null", not just null. No migration, no config change, no action beyond composer update.
• Impersonation and password reset. Check explicitly whether "log in as user" and the reset flow bypass the challenge. If that's a gap for you, close it in your own middleware — don't assume the addon covers it.
• Enforcing before enrolling. Turning on enforcement for a user who never enrolled can strand them. Roll out opt-in first, verify adoption, then enforce.
• Statamic major upgrades. Check the addon's composer.json constraint before bumping Statamic — a Statamic major has historically required a matching addon release.
• Extension points. Published views/config, the service-provider bindings, and the middleware are the intended seams. Editing vendor files means every 2.7.x patch overwrites your work — publish instead.
• Lost device, no recovery codes. Only a DB/CLI reset recovers the account. Document that path before you need it at 2am.