The Hidden Length Mismatch in Password Hash Verification
A common headache for developers implementing password authentication involves a seemingly paradoxical failure mode: the input string and the retrieved database column appear identical when echoed to the screen, yet password_verify consistently returns false. This scenario often points toward invisible character encoding differences or silent truncation rather than simple logic errors.
The core issue usually stems from how PHP handles binary data versus text strings when interacting with MySQL. Password hashes generated by password_hash() are inherently binary-safe; they can contain any byte value and do not conform to standard UTF-8 expectations regarding length. When you store a hash in a column defined as VARCHAR(255), the database engine attempts to treat it as text. If your connection charset is set to something other than utf8mb4 (such as older utf8 or latin1), and if the string contains multi-byte sequences that the specific collation interprets differently, you risk silent truncation.
Consider this: a 255-character limit in UTF-8 does not guarantee 255 bytes of storage if the connection encoding treats some characters as double-width or if the column is strictly interpreted as bytes rather than character units. While password_hash() guarantees a specific length output, storing that binary string into a text column forces an implicit conversion. If the database truncates the string to fit the character limit based on its internal encoding rules, the resulting string passed to password_verify will be shorter than the original hash, causing verification to fail immediately.
You might notice that echoing the values makes them appear identical because PHP's echo function displays the visual representation of the string, not its raw byte length. This creates a false sense of security. The problem becomes apparent when comparing lengths or using strict equality checks against a hardcoded string. In your specific case, the fact that $hash == $hardcode_hash returns true but password_verify fails suggests a potential issue with trailing null bytes or invisible characters that are stripped during the comparison but present in the stored value, or vice versa. However, given the context of VARCHAR storage, truncation is the most probable culprit.
To resolve this, you must ensure your database schema and connection settings support full UTF-8 multibyte characters. Specifically, update your MySQL tables to use utf8mb4 encoding and a compatible collation like utf8mb4_unicode_ci. This ensures that every byte in the hash is treated as a distinct character unit, preventing unexpected truncation when the data enters a VARCHAR(255) column.
Additionally, verify your PHP MySQL connection configuration. If you are using PDO or mysqli, explicitly setting the charset to utf8mb4 upon connection is critical:
$mysqli->set_charset("utf8mb4");
Without this step, even if the table schema is correct, the connection layer might default to a legacy encoding that misinterprets binary data. Once the encoding is aligned, the hash retrieved from the database will retain its full length and byte structure, allowing password_verify() to compare against the original input correctly.
If you are working within an existing codebase using PHP 5.4 with the ircmaxell/password_compat library, these steps remain valid as long as the underlying storage layer is corrected. The password_compat script handles hashing logic but relies on the environment storing the result faithfully. If you transition to modern PHP versions, consider dropping the compatibility layer entirely, as native support for password hashing algorithms has been robust since early 5.x releases.
For projects where schema migration isn't immediately feasible, you can force a byte-level read by retrieving the hash into a binary-safe context or using a BLOB column type, though VARCHAR with proper encoding is generally preferred for readability and indexing efficiency.