Fallback Password Encoder Bundle Laravel Package

Product Decisions This Supports

• Migration vs. forced reset (the core decision). When you inherit a user table with legacy hashes (MD5, SHA1, unsalted, custom schemes), the product fork is: force a global password reset or transparently re-hash on next login. This package exists to make the second option cheap. That's a retention decision disguised as an engineering one — forced resets reliably produce login drop-off, spike support tickets, and depress 7/30-day reactivation, especially for low-frequency B2C users who only log in quarterly.
• Roadmap sequencing for a security modernization program. It lets you ship "we now use bcrypt/Argon2id" as a progressive rollout rather than a big-bang cutover tied to a comms campaign. You can decouple the security milestone (new hashes) from the user-facing milestone (reset prompt), which is usually the difference between a one-sprint change and a quarter-long program.
• Build vs. buy vs. borrow. The real output here is borrow: the package is a ~1-class reference implementation of the "try encoders in order, re-encode the winner" pattern. The decision to make is not "should we add this dependency" but "do we implement this pattern natively in our auth layer." In most stacks the answer is yes, and the answer to vendoring this specific package is usually no.
• M&A / technical due diligence scoping. After an acquisition or replatform, "we don't know what hashing scheme the legacy app used" is a common and expensive finding. An encoder-stack approach converts that unknown into a bounded, estimable work item (one encoder per discovered scheme) instead of an open-ended audit.
• Cohort-level feature decisions. It enables per-user state you can build product on: needs_rehash flags, "legacy account" segments, progressive hardening at login, and risk-based step-up auth for users who haven't rotated credentials since the migration.
• Breach/incident response readiness. A pluggable encoder stack is the mechanism you'd need for a controlled, staged credential rotation rather than an emergency all-users reset — worth having in the plan even if you never use it.
• Not supported: greenfield auth, SSO/OIDC strategy, MFA, session management. This is narrow by design and shouldn't be stretched.

When to Consider This Package

Consider the pattern if:

• You are consolidating two or more user stores (acquisition, replatform, multi-brand) and at least one hashes you can't reproduce natively.
• You cannot force a reset: large low-engagement user base, regulated/brand-sensitive consumer product, or contractual continuity obligations.
• Multiple legacy schemes coexist in the same table and you need ordered fallback plus per-login upgrade.
• You want the security upgrade to be invisible to the user and measurable only in backend metrics.

Look elsewhere — or, more likely, just implement it — if:

• You're on Laravel. This is a Symfony bundle, not a Laravel package. That framework mismatch is disqualifying on its own. Laravel already ships the primitive: Hash::check() plus Hash::needsRehash()/Hash::make() covers the transparent-upgrade loop in a few lines, and custom drivers cover exotic legacy schemes.
• You're on Symfony 4.3+. Use the native MigratingPasswordEncoder and PasswordUpgraderInterface. The framework absorbed this exact pattern years ago; adding a third-party bundle for it is strictly worse.
• You need vendor support, an SLA, or a security disclosure process. 6 stars, 0 dependents, single maintainer: assume bus factor 1, no security response, no compatibility guarantees. In an auth-critical path that's an unacceptable dependency — but fine as a reference to copy from.
• Compliance is in scope (PCI-DSS, SOC 2, ISO 27001). Self-maintained code is perfectly defensible here, but you need provenance, code review, and a patch path — which means forking, not depending.
• The legacy scheme is recoverable. If you can obtain plaintext (partner export, re-registration flow) or the legacy system is still live and can emit a token, a token-based migration is cleaner than hash fallback.

Adoption preconditions if you insist on the dependency: pin the commit, vendor it into your repo, add a test corpus of real legacy hashes, and assign an owner. Otherwise, budget the half-day to reimplement.

How to Pitch It (Stakeholders)

To executives — frame it as a migration cost, not a dependency request. "We have users whose passwords are stored in an obsolete format. The default plan is to email everyone and force a reset. That costs us a campaign, a support surge, and measurable login attrition among exactly the users we least want to lose. The alternative is that we upgrade their credentials silently the next time they log in — the user notices nothing, and we close the security gap within a normal login cycle. The engineering cost is small: days, not a quarter. I'm recommending the silent-upgrade path and explicitly not recommending we take on a new third-party dependency to do it."

To engineering — be precise about what you want and what you don't. "This package is a Symfony bundle, so it doesn't apply to us directly, and with 6 stars and no dependents I wouldn't put it in the auth path regardless. What I want is the pattern it implements: an ordered chain of encoders, attempt each on login, and when a legacy encoder succeeds, immediately re-encode with the modern one and persist it. In Laravel that's Hash::check + Hash::needsRehash inside the login flow; the work is defining one driver per legacy scheme and writing a test fixture for each. Deliverable: legacy users transparently migrate to Argon2id/bcrypt over their next N logins, with a dashboard showing the shrinking needs_rehash cohort. Please treat the linked repo as documentation, not as a dependency."

To security/compliance — pre-empt the objection. "No third-party code enters the authentication path; we implement and own the logic, and it's covered by our normal review and patch process. The upgrade is per-login and idempotent. Users who never return retain a legacy hash, which is a known, tracked residual — we can set a policy date to force-reset the remainder if that's required. We keep the old encoders only as long as the residual cohort exists, then delete them."

One-line version: Skip the package, keep the idea — buy yourself a silent credential migration instead of a forced password reset campaign.