PHP password_needs_rehash 怎么做密码升级：算法变更、登录时机与回滚边界

用户登录成功后，系统里可能还存着好几年前用旧参数生成的 bcrypt 哈希。要是直接全量重置所有用户密码，大概率会堆出大量客服工单还造成登录拥堵，要是完全不动又会让低安全强度的旧哈希长期留在库里。PHP 里对应的渐进式密码升级方案很稳妥：先用 password_verify() 确认用户输入的原密码没问题，再用 password_needs_rehash() 比对当前系统配置的密码策略；两个判断都通过之后，就趁着这次登录成功的时机生成新哈希并存进数据库就行。

先把“密码正确”和“哈希过时”拆成两个独立步骤

password_verify($plain, $hash) 负责处理用户身份认证的问题；password_needs_rehash($hash, $algo, $options) 负责校验现有哈希是否符合当前预设的安全策略。后者返回 true 的时候，只能说明数据库里存的哈希和当前指定的算法或者参数不一致，完全不能证明用户输入的密码是正确的。

所以判断顺序绝对不能反过来：必须先验证密码，再决定要不要升级哈希。就算攻击者已经拿到某条旧哈希的内容，也没法单凭这个就触发系统写入新哈希的操作。

把目标策略集中管理，避免登录逻辑里散落零散参数

建议把密码算法和对应配置参数都放在一个不可变的统一配置里。示例里使用 PASSWORD_DEFAULT，它代表 PHP 当前官方推荐的默认算法；如果你们业务明确要切换到 Argon2id 算法，得先确认运行环境已经完整支持这个算法，全量切换前还要先做好加密耗时和内存占用的测试。

 PASSWORD_DEFAULT,
        'options' => [
            'cost' => 12,
        ],
    ];
}

$policy = currentPasswordPolicy();
$hash = password_hash($plainPassword, $policy['algo'], $policy['options']);

策略配置表里至少要记录算法类型、cost 或者 memory_cost 参数、启用时间和对应的回退方案。不要把自定义固定 salt 写进配置参数里；PHP 每次调用密码生成函数都会自动生成随机 salt，生成出来的哈希字符串本身就已经包含后续验证需要的全部算法和参数信息。

用户成功登录时完成一次渐进升级

标准的登录流程是先从数据库查出对应的用户记录，先校验用户提交的原密码是否正确，再检查旧哈希是否已经不符合当前策略。所有条件都满足的情况下才把新的哈希值写回数据库：

findByEmail($email);
$policy = currentPasswordPolicy();

if (!$user || !password_verify($plainPassword, $user['password_hash'])) {
    throw new RuntimeException('账号或密码不正确');
}

if (password_needs_rehash(
    $user['password_hash'],
    $policy['algo'],
    $policy['options']
)) {
    $newHash = password_hash(
        $plainPassword,
        $policy['algo'],
        $policy['options']
    );

    $userRepository->replacePasswordHash(
        $user['id'],
        $user['password_hash'],
        $newHash
    );
}

issueSessionFor($user['id']);

replacePasswordHash() 最好把旧哈希值放到 UPDATE 的 WHERE 条件里：UPDATE users SET password_hash = :new WHERE id = :id AND password_hash = :old。这样就算两个并发的登录请求都完成了密码校验，后执行写入的请求也不会盲目覆盖前面刚生成的新哈希；如果更新的影响行数是 0，直接理解成“其他请求已经完成了这次升级”就可以，正常给用户创建登录会话就行。

参数变化、数据库长度和回退边界

PASSWORD_DEFAULT 的底层算法可能随着 PHP 大版本升级发生调整，最终生成的哈希字符串长度也会跟着变化。存储密码的字段不要只按照当前某一种算法的最短长度来设计；PHP 官方手册建议要预留足够的余量，通用做法是使用 VARCHAR(255)，在数据库迁移验收环节还要专门检查实际字段的长度是否达标。

回退操作不是把数据库里刚生成的新哈希全部降级重算。更稳妥的处理方式是临时把目标策略切回之前已经跑稳定的算法和参数，让现有所有哈希都能正常完成验证；后续新哈希要不要重新执行升级逻辑，等问题彻底修复之后再处理就好。

上线前用一个旧哈希做完整回归检查

不要只拿空测试数据库调用一遍函数就完事。提前准备一条用旧 cost 生成的测试哈希、一条用当前策略生成的哈希和一组错误密码，分别验证密码校验结果、重算判断逻辑和写库条件是否符合预期。

 10]);
$policy = currentPasswordPolicy();

var_dump(password_verify('demo-pass', $oldHash));
var_dump(password_needs_rehash($oldHash, $policy['algo'], $policy['options']));
var_dump(password_verify('wrong-pass', $oldHash));

验收的核心要求不是每次都返回固定的布尔值，而是要确认三个对应关系：正确密码能正常通过验证，不符合旧策略的哈希会被识别成需要重算，错误密码永远不会走到更新哈希的分支。上线到生产环境之后再持续观察登录耗时、重算触发次数、更新冲突量和异常率，确认升级逻辑没有把认证接口的响应时间拖出可接受范围。

常见问题

password_needs_rehash 会验证用户密码吗？

不会。它只对比已经存好的哈希和目标算法、配置参数是否匹配，调用它之前必须先调用 password_verify() 完成密码校验。

每次登录都需要重新生成哈希吗？

不需要。只有 password_needs_rehash() 返回 true 并且密码验证完全成功的时候才执行升级操作。

哈希升级失败要不要阻止用户登录？

通常不要因为这次非核心的写入失败就打断用户正常登录流程，也不要向外泄露多余的认证细节；你可以记录对应的异常日志，给用户正常创建登录会话，下次用户成功登录的时候还能自动重试升级逻辑。

可以把旧密码先解密再生成新哈希吗？

不应该这么做。密码哈希本身不是可逆的加密密文，渐进升级的逻辑本身就依赖用户在登录时主动输入正确的明文密码来触发。

收尾检查

密码策略升级的核心从来不是“换一个更大的 cost 参数”，而是要把身份认证、重算判断、并发写入和异常回退拆成各个可独立验证的边界步骤。先让 password_verify() 确认用户身份合法，再让 password_needs_rehash() 判断现有哈希是否已经落后，最后用带旧值校验的条件更新把新哈希写回数据库，这套流程可以慢慢覆盖所有活跃用户，同时全程保留旧哈希的可验证性。