wp_password_needs_rehash() │ WP 6.8.0

Checks whether a password hash needs to be rehashed.

Passwords are hashed with bcrypt using the default cost. A password hashed in a prior version of WordPress may still be hashed with phpass and will need to be rehashed. If the default cost or algorithm is changed in PHP or WordPress then a password hashed in a previous version will need to be rehashed.

Note that, just like wp_check_password(), this function may be used to check a value that is not a user password. A plugin may use this function to check a password of a different type, and there may not always be a user ID associated with the password.

Pluggable function — this function can be replaced from a plugin. It means that this function is defined (works) only after all plugins are loaded (included), but before this moment this function has not defined. Therefore, you cannot call this and all functions depended on this function directly from a plugin code. They need to be called on plugins_loaded hook or later, for example on init hook.

Function replacement (override) — in must-use or regular plugin you can create a function with the same name, then it will replace this function.

Hooks from the function

wp_hash_password_algorithm

wp_hash_password_options

password_needs_rehash

Returns

true|false. Whether the hash needs to be rehashed.

Usage

wp_password_needs_rehash( $hash, $user_id );

$hash(string) (required): Hash of a password to check.
$user_id(string|int): ID of a user associated with the password.
Default: ''

Notes

Global. PasswordHash. $wp_hasher phpass object.

Changelog

Since 6.8.0

Introduced.

`wp_password_needs_rehash() wp password needs rehash` code ^{WP 6.8.1}

wp-includes/pluggable.php

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 );
}