hash
Generates a message digest of a string using any algorithm supported by the hash extension.
hash(string $algo, string $data, bool $binary = false, array $options = []): string- Added in PHP 5.1.2
Parameters
| Parameter | Type | Description |
|---|---|---|
$algo | string | Name of the hashing algorithm, for example "sha256". See hash_algos() for the supported list. |
$data | string | The message to be hashed. Binary safe. |
$binaryoptional | bool= false | When true, outputs raw binary data instead of lowercase hexits. |
$optionsoptional | array= [] | Algorithm-specific options. Currently only the "seed" key, used by the MurmurHash variants. |
Return value
stringThe message digest as lowercase hexits, or the raw binary digest when binary is true.
Errors
Throws a ValueError if algo names an algorithm the build does not support.
Changelog
- PHP 8.1.0The options parameter was added, allowing a seed to be passed to the MurmurHash variants.
- PHP 8.0.0An unknown algo now throws a ValueError; previously the function returned false and emitted an E_WARNING.
hash() is the general-purpose digest function. Instead of one algorithm baked into the function name, you pass the algorithm as a string, so the choice can live in configuration and be upgraded without touching call sites.
When to reach for it
Make it your default over md5() and sha1(). Use sha256 for integrity you care about, xxh3 or xxh128 when you want a very fast non-cryptographic fingerprint for cache keys and deduplication, and crc32b when a protocol demands it. All of them go through the same call.
What trips people up
Since PHP 8.0 an unknown algorithm name throws a ValueError rather than returning false. Code written for PHP 7 that checked if ($h === false) will now die with an uncaught exception on a typo'd name. Validate against hash_algos() first, or catch the error.
Algorithm names are matched case-insensitively but are conventionally lowercase, and the available list depends on how PHP was built — hash_algos() is the only reliable source. Finally, hash() is not a keyed function: to authenticate a message with a shared secret use hash_hmac(), never hash('sha256', $secret . $data), which is vulnerable to length-extension.
Example
When to use it
- Fingerprint uploaded files with sha256 so duplicates are detected before storage.
- Build fast cache keys with xxh3 in a hot code path.
- Compute a content hash for cache-busting asset URLs at build time.
Frequently asked questions
What is the difference between hash and hash_hmac?
hash() takes only the data, while hash_hmac() also takes a secret key and produces a value nobody without that key can forge. Use hash() for integrity and hash_hmac() for authenticity.
Which algorithm should I use with hash?
Use sha256 for general integrity and security work, and xxh3 or xxh128 when you only need a fast fingerprint for cache keys. Avoid md5 and sha1 for anything an attacker could target.
Does hash work for passwords?
No. Every algorithm hash() offers is deliberately fast, which is the opposite of what password storage needs. Use password_hash() and password_verify().
More examples
Digest length per algorithm
Each algorithm produces a fixed-width digest regardless of input size: 8 hexits for crc32b up to 128 for sha512. The byte column shows what a BINARY column would need if you store the raw form.
<?php
foreach (['crc32b', 'md5', 'sha1', 'sha256', 'sha512', 'xxh64'] as $algo) {
$hex = hash($algo, 'the same input');
printf("%-8s %2d hexits %2d bytes%s", $algo, strlen($hex), strlen(hash($algo, 'x', true)), PHP_EOL);
}Choosing the algorithm safely at runtime
The guard turns an unsupported name into a handled message instead of an uncaught ValueError. This is the pattern to use whenever the algorithm comes from config, a database or a request.
<?php
function digest(string $algo, string $data): string {
if (!in_array($algo, hash_algos(), true)) {
return "unsupported: $algo";
}
return hash($algo, $data);
}
echo digest('sha256', 'hello'), PHP_EOL;
echo digest('sha3-256', 'hello'), PHP_EOL;
echo digest('md6', 'hello'), PHP_EOL;
Discussion