hash_init

Initialize an incremental hashing context

Description

HashContext hash_init(
    string $algo,
    int $flags = 0,
    #[\SensitiveParameter]string $key = "",
    array $options = []
)

Parameters

algo

Name of selected hashing algorithm (e.g. "sha256"). For a list of supported algorithms see hash_algos.

Note:

Non-cryptographic hash functions are not allowed if the HASH_HMAC flag is specified.

flags

Optional settings for hash generation, currently supports only one option: HASH_HMAC. When specified, the key must be specified.

key

When HASH_HMAC is specified for flags, a shared secret key to be used with the HMAC hashing method must be supplied in this parameter.

options

An array of options for the various hashing algorithms:

'seed' (int)
Supported by MurmurHash3 and XXHash variants.
'secret' (string)
Supported by xxh3 and xxh128.

Return Values

Returns a Hashing Context for use with hash_update, hash_update_stream, hash_update_file, and hash_final.

Errors/Exceptions

  • Throws a ValueError exception if algo is unknown or is a non-cryptographic hash function, or if key is empty.
  • Passing configurations options of the wrong type in options will now emit an E_DEPRECATED error because they can be interpreted incorrectly. This will become a ValueError in the future.

Changelog

Version Description
8.4.0 Passing options of a wrong type is now deprecated.
8.1.0 The options parameter has been added.
8.0.0 Now throws an ValueError exception if the algo is unknown or is a non-cryptographic hash function, or if key is empty. Previously, false was returned and an E_WARNING message was emitted.
7.2.0 Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) with HASH_HMAC was disabled.
7.2.0 Return HashContext instead of resource.

Examples

Example #1 Incremental hashing example

<?php
$hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');

$ctx = hash_init('sha256');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
$incremental_hash = hash_final($ctx);

echo $incremental_hash, PHP_EOL;
var_dump($hash === $incremental_hash);
?>

The above example will output:

68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
bool(true)

See Also

  • hash_algos
  • hash_update
  • hash_update_file
  • hash_update_stream
  • hash_final