scheb/2fa-backup-code

scheb/2fa-backup-code is a plugin package for the scheb/2fa two-factor authentication suite that adds backup (recovery) code support to Symfony applications. It lets users complete two-factor authentication with a set of one-time backup codes when their primary second factor is unavailable.

Built on top of scheb/2fa-bundle, it plugs into the bundle’s authentication flow through a small set of interfaces and managers, so you can store, validate, and invalidate backup codes against your own user model with minimal integration code.

What You Get

• A BackupCodeInterface for your user entity to expose valid backup codes
• A BackupCodeManager that checks and invalidates codes during authentication
• A NullBackupCodeManager for setups without backup-code persistence
• Backup-code events so your app can react when a code is consumed

Common Use Cases

• Giving users recovery codes to log in when they lose their authenticator device
• Adding a fallback second factor to a Symfony app already using scheb/2fa
• Invalidating and rotating one-time backup codes after each use

Under The Hood

Architecture - The package is a thin, focused extension of scheb/2fa-bundle. Its Security/TwoFactor/Backup directory contains the BackupCodeManager (plus interface and a Null implementation), Security/Http/EventListener/CheckBackupCodeListener hooks into the bundle’s authentication event flow to accept a backup code, and Model/BackupCodeInterface defines the contract your user model implements.

Tech Stack - It is a small PHP library (composer type library) whose only runtime requirements are PHP and scheb/2fa-bundle. It ships as part of the scheb/2fa monorepo and is distributed as a read-only Composer split.

Code Quality - The code is minimal and interface-driven, and the parent scheb/2fa project maintains CI, Codecov coverage, and a shared test suite across its packages. Within this split the surface is a handful of small, single-responsibility classes.

API Design - Integration is declarative: implement BackupCodeInterface on your user, wire the manager, and the listener handles the rest. The interface-plus-manager pattern keeps the package decoupled from any particular storage mechanism.