password_needs_rehash()

password_needs_rehash() — Checks if the given hash matches the given options.

Built-in function of PHP 8.5. The manual lists it as available in PHP 5 >= 5.5.0, PHP 7, PHP 8. This page is the reference card: signature, parameters and return value, plus the changelog and the example the manual provides.

What it does

This function checks to see if the supplied hash implements the algorithm and options provided. If not, it is assumed that the hash needs to be rehashed.

Signature

password_needs_rehash(string $hash, string|int|null $algo, array $options = []): bool

Parameters

Return value

Returns true if the hash should be rehashed to match the given algo and options, or false otherwise.

Example

A runnable snippet:

$password = 'rasmuslerdorf'; $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.'; $algorithm = PASSWORD_BCRYPT; // bcrypt's cost parameter can change over time as hardware improves $options = ['cost' => 13]; // Verify stored hash against plain-text password if (password_verify($password, $hash)) { // Check if either the algorithm or the options have changed if (password_needs_rehash($hash, $algorithm, $options)) { // If so, create a new hash, and replace the old one $newHash = password_hash($password, $algorithm, $options); // Update the user record with the $newHash } // Perform the login. }

Changelog

All PHP 8.5 built-in functions

Reference card built from the PHP manual page password_needs_rehash() (PHP documentation, CC BY 3.0). The page is generated from the manual, so the wording of the parameter and return value text follows php.net.