Securely Hash Passwords with Argon2 in PHP

<?php
// --- Password Hashing ---
/**
 * Hashes a plain-text password using the Argon2ID algorithm.
 * @param string $password The plain-text password to hash.
 * @return string The hashed password.
 */
function hashPassword(string $password): string {
    // PASSWORD_ARGON2ID is currently the strongest and recommended algorithm.
    // It's a hybrid of Argon2i and Argon2d, resisting side-channel timing attacks
    // and GPU cracking.
    // Defaults: MEMORY_COST=65536 (64MB), TIME_COST=4, THREADS=1
    // You can customize options if needed:
    // $options = [
    //     'memory_cost' => 1<<17, // 128MB
    //     'time_cost'   => 5,
    //     'threads'     => 2,
    // ];
    // return password_hash($password, PASSWORD_ARGON2ID, $options);
    return password_hash($password, PASSWORD_ARGON2ID);
}

// --- Password Verification ---
/**
 * Verifies a plain-text password against a stored hash.
 * @param string $password The plain-text password to verify.
 * @param string $hash The stored password hash.
 * @return bool True if the password matches the hash, false otherwise.
 */
function verifyPassword(string $password, string $hash): bool {
    return password_verify($password, $hash);
}

// Example Usage:

// 1. Registering a new user
$plainPassword = "MySuperSecretPassword123!";
$hashedPassword = hashPassword($plainPassword);
echo "Hashed password: " . $hashedPassword . "
";
// Store $hashedPassword in your database.

// 2. Logging in a user
$userProvidedPassword = "MySuperSecretPassword123!"; // From login form
// Retrieve $storedHash from the database for the given username/email
$storedHash = '$argon2id$v=19$m=65536,t=4,p=1$cT9tYm1XVE1TNUhKczl5Yw$C42G/L5FhQf2/H1zXh7XQz/5f1lQ/gL7kX3Zp/G2KzQ'; // Example hash

if (verifyPassword($userProvidedPassword, $storedHash)) {
    echo "Login successful!
";
} else {
    echo "Login failed. Invalid credentials.
";
}

// Check if a hash needs to be rehashed (e.g., if options changed or a newer algorithm is available)
if (password_needs_rehash($storedHash, PASSWORD_ARGON2ID)) {
    echo "Password needs re-hashing with updated parameters.
";
    $newHashedPassword = hashPassword($userProvidedPassword); // Re-hash and update in DB
    echo "New hashed password: " . $newHashedPassword . "
";
}
?>