PHP 8.1: Hash functions accept algorithm-specific $options

Version8.1
TypeNew Feature

Hash functions in PHP accept a new optional $options parameter in PHP 8.1, that can further specify custom algorithm-specific options.

The following functions accept the new $options parameter as their last parameter:

Function synopses

function hash(string $algo, string $data, bool $binary = false, array $options = []): string|false
function hash_file(string $algo, string $filename, bool $binary = false, array $options = []): string|false
function hash_init(string $algo, int $flags = 0, string $key = '', array $options = []): HashContext

Supported Custom Options

MurmurHash3 and xxHash algorithms support specifying custom options with the new $options parameter.

hash('murmur3f', 'php.watch'); // "ba0189037daec822d973d304602d44f0"
hash("murmur3f", "php.watch", options: ["seed" => 42]); // 0cafc26e49efe230cdbd109458fef893
hash("xxh3", "php.watch"); // "f406cee14d73b176"
hash("xxh3", "php.watch", options: ["seed" => 44]); // acb8c705fdcd579c

These snippet use named parameters introduced in PHP 8.0.

In PHP 8.1, the following new hash $option values are accepted:

Backwards Compatibility Impact

The new $options parameter is a new parameter with a default value of an empty array, and will not cause any backwards-compatibility issues if the hash* functions are called with the additional $options parameter. PHP will silently ignore the additional parameters, but note that the output will be different across PHP versions without $options parameter support.

As of now, the only hashing algorithms that support custom options are MurmurHash3 and xxHash algorithms added in PHP 8.1.

Related Changes

Implementation