PHP 中 password_hash() 返回 null 的原因及正确用法-php教程-PHP中文网

PHP 中 password_hash() 返回 null 的原因及正确用法

password_hash() 返回 null 通常是因为调用时参数缺失（至少需传入密码和算法），而非密码为空；本文详解其必填参数、常见错误、安全实践及调试方法。

`password_hash()` 返回 `null` 通常是因为调用时参数缺失（至少需传入密码和算法），而非密码为空；本文详解其必填参数、常见错误、安全实践及调试方法。

在 PHP 中，password_hash() 是一个用于安全生成密码哈希的标准函数，但若使用不当，极易返回 null —— 尤其当开发者误以为它仅需一个参数时。你提供的代码中：

$passw = password_hash($password); // ❌ 错误：缺少必需的第二个参数

该调用不符合函数签名要求，导致 password_hash() 静默失败并返回 null（PHP 8.0+ 会触发 E_WARNING；低版本可能仅返回 null 且无提示）。

✅ 正确调用方式：必须指定算法

password_hash() 的完整签名如下：

string|false password_hash(string $password, int $algo, array $options = [])

$password：待哈希的明文密码（非空字符串）；
$algo：必需，指定哈希算法，推荐使用 PASSWORD_ARGON2ID（PHP ≥ 7.3）或兼容性更广的 PASSWORD_DEFAULT（当前等价于 bcrypt，未来可能升级）；
$options：可选，用于配置盐、成本因子等（通常可省略，默认安全）。

✅ 正确示例：

// 推荐：使用 PASSWORD_DEFAULT（自动适配最佳算法）
$hash = password_hash($password, PASSWORD_DEFAULT);
if ($hash === false) {
    throw new RuntimeException('密码哈希失败，请检查 PHP 版本与配置');
}
echo $hash; // 输出类似: $2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi

⚠️ 注意事项：

不要硬编码算法常量为整数（如 1），应始终使用 PASSWORD_* 常量；
PASSWORD_DEFAULT 是安全首选——它随 PHP 升级自动启用更强算法，且 password_verify() 可向后兼容旧哈希；
若需固定算法（如部署限制），可显式使用 PASSWORD_ARGON2ID 或 PASSWORD_BCRYPT，但须确保环境支持；
password_hash() 不接受 null 或非字符串类型：若 $password 是 null、false 或数字，将返回 false（非 null），因此 var_dump($passw) 显示 null 几乎必定源于参数缺失。

? 调试建议

开启错误报告（开发环境必备）：

图片转Word
将扫描图像、截图或表单、文档及以文字为主的图片内容，转换为可编辑的 Word（.docx）文件。当用户提供包含文本内容的图片，并要求将其转为 Word 文档时，应使用此技能；或用户表达类似“把图片搞成 word 文字版”、“convert image to docx”、“extract text from image to Word”等需求时，也应调用此技能。

下载
```
error_reporting(E_ALL);
ini_set('display_errors', '1');
```
缺失参数时将提示：Warning: password_hash() expects at least 2 parameters, 1 given。

验证输入类型：

if (!is_string($password) || trim($password) === '') {
    throw new InvalidArgumentException('密码必须是非空字符串');
}

检查 PHP 版本：PASSWORD_ARGON2ID 需 PHP ≥ 7.3 且编译时启用 libsodium；PASSWORD_DEFAULT 自 PHP 5.5.0 起可用。

✅ 完整修复后的注册逻辑节选

if (empty($password)) {
    echo "Dieses Feld darf nicht leer sein!";
    $error = true;
} else {
    // ✅ 正确哈希：指定算法
    $hash = password_hash($password, PASSWORD_DEFAULT);
    if ($hash === false) {
        error_log('password_hash failed for user: ' . $username);
        echo "Systemfehler bei der Passwortsicherung.";
        $error = true;
    } else {
        $registerService = new RegisterService();
        try {
            $session = $registerService->insertRegisteredUser($username, $hash); // 传入哈希值，非明文！
            echo json_encode(["success" => 1]);
        } catch (Exception $e) {
            error_log('Registration failed: ' . $e->getMessage());
            echo json_encode(["success" => 0]);
        }
    }
}