PHP 8.1: xxHash hash algorithms support
xxHash is an extremely fast hashing algorithm that is not designed for cryptographic purposes, but provides excellent randomness and dispersion of output, and uniqueness of to minimize collisions. Some xxHash variants in fact, are faster than the RAM throughput provided CPU cache is sufficient and fits.
PHP 8.1 adds support for xxHash algorithm in following variants:
xxh32: 32-bit hash output
xxh64: 64-bit hash output
xxh3: 64-bit hash output
xxh128: 128-bit hash output
hash('xxh32', 'php.watch'); // cb729dd1 hash('xxh64', 'php.watch'); // 9c823891d744a55e hash('xxh3', 'php.watch'); // f406cee14d73b176 hash('xxh128', 'php.watch'); // 16c27099bd855aff3b3efe27980515ad
xxHash is a streaming hash, and can be used as such:
$context = hash_init('xxh3'); hash_update($context, 'php.'); hash_update($context, 'watch'); hash_final($context); // f406cee14d73b176
xxHash is not a cryptographic hashing algorithm. For password hashing, use
password_hashand its friends. Furthermore, none of the xxHash variants are allowed in
In PHP 8.1, xxHash is the fastest hashing algorithm supported in PHP.
|Algorithm||PHP implementation speed (GB/s)|
The results above are an excerpt from PHP Hash Algorithm Benchmarks.
PHP 8.1 supports specifying algorithm-specific options with the new
$options parameter. Along with this,
xxh* hashing algorithms accept additional options:
Only one option is accepted at a time. For example, if a
seed option is specified, it cannot use a
secret option in the same hashing operation.
seed options are passed, an Error will be thrown.
hash("xxh3", "php.watch", false, ["secret" => $secret, 'seed' => 43]);
xxh3: Only one of seed or secret is to be passed for initialization in ... on line ...
All xxHash variants accept a
seed option through the third parameter (
$options) of the
hash('xxh3', 'php.watch'); // "f406cee14d73b176" hash("xxh3", "php.watch", false, ["seed" => 42]); // de9956536d1e9543 hash("xxh3", "php.watch", options: ["seed" => 42]); // de9956536d1e9543
The third example uses named parameters introduced in PHP 8.0.
xxh128 variants of xxHash accept a
secret value in the third parameter (
The required key must be larger than 135 bytes, and a key longer than 256 bytes will discarded with a warning emitted.
$secret = random_bytes(256); hash("xxh3", "php.watch", false, ["secret" => $secret]); // "a0dad59ce6341fb0"
It is important that the
secret value has a sufficient entropy. PHP built-in
random_bytes function is a cryptographically secure random-number generator.
xxh64 variants do not recognize a
secret option, and if passed, it will be silently ignored.
secretvalue smaller than 136 bytes causes an error:
hash("xxh3", "php.watch", false, ["secret" => 'ab'])
xxh3: Secret length must be >= 136 bytes, ... bytes passed in ... code on line ...
secretvalue larger than 256 bytes makes PHP trim the value to 256 bytes with a warning:
hash("xxh3", "php.watch", false, ["secret" => str_repeat('a', 257)]);
hash(): xxh3: Secret content exceeding 256 bytes discarded in ... code on line ...
Backwards Compatibility Impact
xxHash is newly added to PHP 8.1, and older PHP versions will not be able to use xxHash algorithms via
Attempting to use xxHash algorithms in
hash function results in a
Fatal error: Uncaught ValueError: hash(): Argument #1 ($algo) must be a valid hashing algorithm in ...:...
On PHP versions prior to 8.0, a warning will be raised:
Warning: hash(): Unknown hashing algorithm: xxh3 in ... on line ...
Alternatives implementations include:
- Megasaxon/php-xxhash - A PHP extension to add
xxhash64for xxHash variants.
- exussum12/xxhash - A pure-PHP implementation with FFI support. The pure-PHP implementation is ~600x slower than the native code, and the FFI implementation is only ~0.4x slower.
- PHP 8.1: Hash functions accept algorithm-specific
- PHP 8.1: MurmurHash3 hash algorithm support