Password Upgrade Review Plan

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Password Upgrade Review Plan.
 *
 * Purpose:
 * Verifies a password and reports whether the stored hash should be replaced
 * with a stronger current hash.
 *
 * @param string $plain_password Login password submitted by the user.
 * @param string $stored_hash Existing password hash from storage.
 * @return array Verification and upgrade decision.
 */
function ogSnippetPasswordUpgradeReviewPlan(string $plain_password, string $stored_hash): array {
	if (password_verify($plain_password, $stored_hash) === false) {
		return array(
			'password_valid' => false,
			'needs_upgrade' => false,
			'new_hash' => ''
		);
	}

	$needs_upgrade = password_needs_rehash($stored_hash, PASSWORD_DEFAULT);
	$new_hash = '';

	if ($needs_upgrade === true) {
		$created_hash = password_hash($plain_password, PASSWORD_DEFAULT);

		if (is_string($created_hash) === true) {
			$new_hash = $created_hash;
		}
	}

	return array(
		'password_valid' => true,
		'needs_upgrade' => $needs_upgrade,
		'new_hash' => $new_hash
	);
}

$stargate_hash = password_hash('chevron-seven-locked', PASSWORD_DEFAULT);

if (is_string($stargate_hash) === true) {
	$password_review = ogSnippetPasswordUpgradeReviewPlan('chevron-seven-locked', $stargate_hash);

	if ($password_review['password_valid'] === true) {
		echo 'Stargate password accepted.';
	}
}