概述

wp_password_needs_rehash() 函数用于检查密码哈希是否需要重新哈希，以应对 WordPress 版本更新或 PHP 默认设置变更。它支持自定义算法和选项，并可应用于非用户密码场景。

关键要点

• 检查密码哈希是否需要重新哈希，例如当默认成本或算法在 PHP 或 WordPress 中更改时。
• 使用 bcrypt 作为默认哈希算法，但旧版本可能使用 phpass，需要重新哈希。
• 函数可用于检查非用户密码，如插件中的其他类型密码，且不一定关联用户 ID。
• 通过过滤器 wp_hash_password_algorithm 和 wp_hash_password_options 支持自定义算法和选项。
• 返回布尔值，表示哈希是否需要重新哈希。

代码示例

function wp_password_needs_rehash( $hash, $user_id = '' ) {
    global $wp_hasher;

    if ( ! empty( $wp_hasher ) ) {
        return false;
    }

    /** This filter is documented in wp-includes/pluggable.php */
    $algorithm = apply_filters( 'wp_hash_password_algorithm', PASSWORD_BCRYPT );

    /** This filter is documented in wp-includes/pluggable.php */
    $options = apply_filters( 'wp_hash_password_options', array(), $algorithm );

    $prefixed = str_starts_with( $hash, '$wp' );

    if ( ( PASSWORD_BCRYPT === $algorithm ) && ! $prefixed ) {
        // If bcrypt is in use and the hash is not prefixed then it needs to be rehashed.
        $needs_rehash = true;
    } else {
        // Otherwise check the hash minus its prefix if necessary.
        $hash_to_check = $prefixed ? substr( $hash, 3 ) : $hash;
        $needs_rehash  = password_needs_rehash( $hash_to_check, $algorithm, $options );
    }

    /**
     * Filters whether the password hash needs to be rehashed.
     *
     * @since 6.8.0
     *
     * @param bool       $needs_rehash Whether the password hash needs to be rehashed.
     * @param string     $hash         The password hash.
     * @param string|int $user_id      Optional. ID of a user associated with the password.
     */
    return apply_filters( 'password_needs_rehash', $needs_rehash, $hash, $user_id );
}

注意事项

• 函数在 WordPress 6.8.0 版本中引入。
• 如果 $wp_hasher 全局变量非空，函数直接返回 false，这可能影响某些自定义哈希场景。
• 使用过滤器 password_needs_rehash 可进一步控制是否需要重新哈希。