reference/hash/functions/hash-init.xml
20dcfbb0dd7150cbe5dfd7903a3001229295c549
...
...
@@ -11,8 +11,9 @@
11
11
<methodsynopsis>
12
12
<type>HashContext</type><methodname>hash_init</methodname>
13
13
<methodparam><type>string</type><parameter>algo</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>key</parameter><initializer>&null;</initializer></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
15
+
<methodparam choice="opt"><type>string</type><parameter>key</parameter><initializer>""</initializer></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
16
17
</methodsynopsis>
17
18

18
19
</refsect1>
...
...
@@ -29,7 +30,7 @@
29
30
</listitem>
30
31
</varlistentry>
31
32
<varlistentry>
32
-
<term><parameter>options</parameter></term>
33
+
<term><parameter>flags</parameter></term>
33
34
<listitem>
34
35
<para>
35
36
Optional settings for hash generation, currently supports only one option:
...
...
@@ -42,12 +43,21 @@
42
43
<term><parameter>key</parameter></term>
43
44
<listitem>
44
45
<para>
45
-
When <constant>HASH_HMAC</constant> is specified for <parameter>options</parameter>,
46
+
When <constant>HASH_HMAC</constant> is specified for <parameter>flags</parameter>,
46
47
a shared secret key to be used with the HMAC hashing method must be supplied in this
47
48
parameter.
48
49
</para>
49
50
</listitem>
50
51
</varlistentry>
52
+
<varlistentry>
53
+
<term><parameter>options</parameter></term>
54
+
<listitem>
55
+
<para>
56
+
An array of options for the various hashing algorithms. Currently, only the "seed" parameter is
57
+
supported by the MurmurHash variants.
58
+
</para>
59
+
</listitem>
60
+
</varlistentry>
51
61
</variablelist>
52
62
</para>
53
63
</refsect1>
...
...
@@ -61,6 +71,15 @@
61
71
</para>
62
72
</refsect1>
63
73

74
+
<refsect1 role="errors">
75
+
&reftitle.errors;
76
+
<para>
77
+
Throws a <classname>ValueError</classname> exception if
78
+
<parameter>algo</parameter> is unknown or is a non-cryptographic hash
79
+
function, or if <parameter>key</parameter> is empty.
80
+
</para>
81
+
</refsect1>
82
+

64
83
<refsect1 role="changelog">
65
84
&reftitle.changelog;
66
85
<para>
...
...
@@ -74,6 +93,20 @@
74
93
</thead>
75
94
<tbody>
76
95
<row>
96
+
<entry>8.1.0</entry>
97
+
<entry>The <parameter>options</parameter> parameter has been added.</entry>
98
+
</row>
99
+
<row>
100
+
<entry>8.0.0</entry>
101
+
<entry>
102
+
Now throws an <classname>ValueError</classname> exception if the
103
+
<parameter>algo</parameter> is unknown or is a non-cryptographic hash
104
+
function, or if <parameter>key</parameter> is empty. Previously,
105
+
&false; was returned and an <constant>E_WARNING</constant> message was
106
+
emitted.
107
+
</entry>
108
+
</row>
109
+
<row>
77
110
<entry>7.2.0</entry>
78
111
<entry>Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) with <constant>HASH_HMAC</constant> was disabled.</entry>
79
112
</row>
...
...
@@ -97,17 +130,23 @@
97
130
<programlisting role="php">
98
131
<![CDATA[
99
132
<?php
100
-
$ctx = hash_init('md5');
133
+
$hash = hash('sha256', 'The quick brown fox jumped over the lazy dog.');
134
+

135
+
$ctx = hash_init('sha256');
101
136
hash_update($ctx, 'The quick brown fox ');
102
137
hash_update($ctx, 'jumped over the lazy dog.');
103
-
echo hash_final($ctx);
138
+
$incremental_hash = hash_final($ctx);
139
+

140
+
echo $incremental_hash, PHP_EOL;
141
+
var_dump($hash === $incremental_hash);
104
142
?>
105
143
]]>
106
144
</programlisting>
107
145
&example.outputs;
108
146
<screen>
109
147
<![CDATA[
110
-
5c6ffbdd40d9556b73a21e63c3e0e904
148
+
68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483
149
+
bool(true)
111
150
]]>
112
151
</screen>
113
152
</example>
...
...
@@ -128,7 +167,6 @@ echo hash_final($ctx);
128
167
</refsect1>
129
168

130
169
</refentry>
131
-

132
170
<!-- Keep this comment at the end of the file
133
171
Local variables:
134
172
mode: sgml
135
173