PHP
password_needs_rehash()
Learn to upgrade outdated hashes to a new algorithm with password_needs_rehash().
What does password_needs_rehash do?
The password_needs_rehash() function checks whether a stored hash should be recomputed with a stronger algorithm or a higher cost. After a PHP upgrade or a cost bump, old hashes still verify with password_verify but are weaker than the new default.
On successful login you call password_needs_rehash; if it returns true, recompute with password_hash and store it. This pattern is called transparent rehash; the hash migrates silently without the user noticing. The salt ($salt) is generated automatically on every call, you do not produce it yourself.
bcrypt cost and argon2id
PASSWORD_BCRYPT is a cost-based algorithm; the cost option controls how slow each call is. The default cost is 10; each step doubles the time. PASSWORD_ARGON2ID is a memory-hard algorithm; it is tuned with memory_cost, time_cost and threads. The recommended choice for new systems is argon2id.
password_needs_rehash compares the old hash's algorithm and options against the current settings; it returns true on mismatch. So a migration from bcrypt to argon2id, or a cost bump from 10 to 12, happens inside an ordinary login flow.
Exercise Write a transparent rehash function
Define a rehashIfNeeded($password, $hash) function. Inside it, call password_verify($password, $hash); return -1 if false. If true, call password_needs_rehash($hash, PASSWORD_BCRYPT, ["cost" => 10]); return 1 when it is true, 0 otherwise. The $storedHash variable is defined with cost=4. Call rehashIfNeeded("gizli123", $storedHash) and rehashIfNeeded("wrong", $storedHash); print each result with echo.
Show example solution
0; }. $storedHash is defined with cost=4 so needs_rehash returns true; make two calls and print with echo.
Example solution:
<?php
$storedHash = password_hash("gizli123", PASSWORD_BCRYPT, ["cost" => 4]);
function rehashIfNeeded($password, $hash) {
if (!password_verify($password, $hash)) {
return -1;
}
return password_needs_rehash($hash, PASSWORD_BCRYPT, ["cost" => 10]) ? 1 : 0;
}
echo rehashIfNeeded("gizli123", $storedHash) . "\n";
echo rehashIfNeeded("wrong", $storedHash) . "\n";
Test yourself
-
When should password_needs_rehash be called?
- On every page load, regardless of user
- After a successful login, when password_verify is true
- Only when the password is changed
- Never; PHP does this automatically
Show answer
After a successful login, when password_verify is true — Correct. It is called after a successful login; the hash upgrades silently.
-
Complete the password_needs_rehash call
$needsRehash = ____($hash, PASSWORD_DEFAULT, $options);
Show answer
$needsRehash = password_needs_rehash($hash, PASSWORD_DEFAULT, $options);
-
Match the password_needs_rehash concepts
- password_needs_rehash
- Upgrade needed?
- PASSWORD_ARGON2ID
- Memory-hard algorithm
- cost
- bcrypt cost factor
- transparent_rehash
- Silent upgrade on login
Next lesson: Rate limiting
