PragmaRX Recovery

PragmaRX Recovery is a small, focused PHP library for one job: generating the list of backup/recovery codes you hand a user after they enable two-factor authentication, so they can still get into their account if they lose their authenticator device. It builds on pragmarx/random for the underlying random string generation and exposes a fluent Recovery object to control how many codes to generate, how they’re chunked into blocks, and what characters they use.

It has no opinion about how codes are stored, hashed, or verified — that part is left to the consuming application (commonly paired with pragmarx/google2fa in Laravel apps). It only produces the codes themselves, as a plain array, a JSON string, or (if tightenco/collect or Laravel is available) a Collection.

What You Get

• A fluent Recovery class with setCount(), setBlocks(), setChars(), and setBlockSeparator() to control code shape
• numeric()/alpha() and lowercase()/uppercase()/mixedcase() toggles for character set and casing
• Three output formats: toArray(), toJson(), and toCollection() (using Laravel’s or Tighten’s collection helper, or a custom collection function)
• Delegation to pragmarx/random for the underlying cryptographically-flavored random string generation rather than reinventing randomness

Common Use Cases

• Generating the 8-code (or custom count) recovery list shown once after a user enables 2FA/Google Authenticator, typically alongside pragmarx/google2fa
• Laravel applications that want the recovery codes back as a Collection to store, hash, and display consistently with the rest of the app’s data
• Non-Laravel PHP apps that just need a plain array or JSON blob of backup codes to persist and show to the user once
• Customizing code format (numeric-only PINs vs. alphanumeric blocks) to match an existing account-recovery UX

Under The Hood

Architecture — A single Recovery class (src/Recovery.php, ~312 lines) wraps a Random instance from the sibling pragmarx/random package. Calling any to*() method triggers generate(), which resets internal state and loops count times building each code via generateBlocks() — joining blocks chunks of chars random characters with the configured separator. Configuration is expressed as chainable setters (setCount, setBlocks, setChars, setBlockSeparator, numeric/alpha, lowercase/uppercase/mixedcase) that mutate the object before the terminal toArray()/toJson()/toCollection() call reads the generated codes back out. Tech Stack — Plain PHP (>=7.0) with a single runtime dependency, pragmarx/random (~0.1), for randomness. Dev dependencies are PHPUnit and PHP_CodeSniffer (PSR-2), plus an optional tightenco/collect for collection support outside Laravel. Code Quality — A single tests/RecoveryTest.php file covers the public API (count, blocks, chars, casing, separators, array/JSON/collection output); the codebase itself is old-style PHP (no strict_types, no type hints beyond docblocks) consistent with its 2017 origin, and has seen only one tagged release (v0.2.1) with no commits since 2024. API Design — The fluent, chainable setter API (->setCount(8)->setBlocks(5)->setChars(16)->toArray()) reads naturally and requires almost no boilerplate to get from zero to a list of codes, though the class holds mutable internal state across calls rather than being immutable, so reused instances need numeric()/alpha() etc. reset explicitly between calls if defaults are needed again.