Password Hashing

Introduction

In the previous lesson, a login script called password_hash() and password_verify() without much explanation. This lesson looks at those two functions closely, along with password_needs_rehash(), and explains the reasoning behind PHP's modern password-handling API.

Password hashing is one of the few areas of web development where "just write it yourself" is almost always the wrong instinct. PHP's built-in functions exist precisely so you never have to design your own hashing scheme.

Why Not Store Passwords as Plain Text?

If a database storing plain-text passwords is ever leaked — through a breach, a misconfigured backup, or an insider — every account on it is instantly compromised, and because many people reuse passwords, accounts on other sites become vulnerable too.

Hashing solves this by transforming the password into a fixed-length string that cannot practically be reversed back into the original password. The database stores only that hash. Even the application itself never needs to "read back" the real password — it only ever needs to check whether a newly submitted password produces a matching result.

Hashing with password_hash()

PHP's password_hash() function takes a plain-text password and returns a secure hash string, using bcrypt by default (PASSWORD_DEFAULT). Bcrypt automatically generates and embeds a random "salt" into the resulting hash, so two users with the identical password still get completely different stored hashes.

<?php
$plainPassword = 'MySecret123';

$hash = password_hash($plainPassword, PASSWORD_DEFAULT);

echo $hash;

$2y$10$uW9x1eIRlv1v8k4hT.d3Ee3vFZ5J2z8y1uQxWn0nD0p3G8kQxJm9K

Every call to password_hash() with the same input produces a different-looking hash, because a new random salt is generated each time. That is expected and by design — it does not mean the function is broken.

Verifying with password_verify()

To check a login attempt, you never hash the submitted password and compare it to the stored hash with ==. Instead, password_verify() takes the plain submitted password and the stored hash, and internally re-derives whether they match — including using the same salt that was embedded in the original hash.

<?php
$submittedPassword = 'MySecret123';
$storedHash = '$2y$10$uW9x1eIRlv1v8k4hT.d3Ee3vFZ5J2z8y1uQxWn0nD0p3G8kQxJm9K'; // fetched from the database

if (password_verify($submittedPassword, $storedHash)) {
    echo 'Password is correct.';
} else {
    echo 'Password is incorrect.';
}

Password is correct.

Upgrading Hashes: password_needs_rehash()

Hashing algorithms and their recommended settings (like bcrypt's "cost" factor) improve over time. password_needs_rehash() lets an application check, at login time, whether a previously stored hash was created with older or weaker options than the ones currently configured — and if so, re-hash and update it.

<?php
if (password_verify($submittedPassword, $storedHash)) {
    if (password_needs_rehash($storedHash, PASSWORD_DEFAULT)) {
        $newHash = password_hash($submittedPassword, PASSWORD_DEFAULT);
        // Save $newHash to the database, replacing $storedHash
    }

    $_SESSION['user_id'] = $user['id'];
}

This check only makes sense right after a successful password_verify() call, because rehashing requires the plain-text password, which is only available at the moment the user typed it in.

Hashing vs Encryption

Hashing and encryption are often confused, but they solve different problems and are not interchangeable.

Putting It Together

Here is the registration-and-login pair from the previous lesson, now fully explained in terms of the three functions covered here.

<?php
$hashedPassword = password_hash($_POST['password'], PASSWORD_DEFAULT);
// Save $hashedPassword to the database — never the raw password

<?php
if (password_verify($_POST['password'], $user['password'])) {
    if (password_needs_rehash($user['password'], PASSWORD_DEFAULT)) {
        $updatedHash = password_hash($_POST['password'], PASSWORD_DEFAULT);
        // Update the stored hash in the database
    }

    $_SESSION['user_id'] = $user['id'];
}

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

PHP's password_hash() and password_verify() functions give you a secure, battle-tested way to store and check passwords without ever designing your own cryptography. password_needs_rehash() keeps those hashes current as security recommendations evolve.

With authentication and password handling covered, the next lesson turns to a different everyday need: sending email from a PHP application.