reference/password/functions/password-needs-rehash.xml
ff492e168a557e4dd17574023b7c3cb21b14df3b
ff492e168a557e4dd17574023b7c3cb21b14df3b
...
...
@@ -10,10 +10,10 @@
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<methodsynopsis>
13
-
<type>boolean</type><methodname>password_needs_rehash</methodname>
13
+
<type>bool</type><methodname>password_needs_rehash</methodname>
14
14
<methodparam><type>string</type><parameter>hash</parameter></methodparam>
15
-
<methodparam><type>integer</type><parameter>algo</parameter></methodparam>
16
-
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
15
+
<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>
16
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
This function checks to see if the supplied hash implements the algorithm
...
...
@@ -52,6 +52,40 @@
52
52
</variablelist>
53
53
</refsect1>
54
54
55
+
<refsect1 role="returnvalues">
56
+
&reftitle.returnvalues;
57
+
<para>
58
+
Returns &true; if the hash should be rehashed to match the given
59
+
<parameter>algo</parameter> and <parameter>options</parameter>, or &false;
60
+
otherwise.
61
+
</para>
62
+
</refsect1>
63
+
64
+
<refsect1 role="changelog">
65
+
&reftitle.changelog;
66
+
<para>
67
+
<informaltable>
68
+
<tgroup cols="2">
69
+
<thead>
70
+
<row>
71
+
<entry>&Version;</entry>
72
+
<entry>&Description;</entry>
73
+
</row>
74
+
</thead>
75
+
<tbody>
76
+
<row>
77
+
<entry>7.4.0</entry>
78
+
<entry>
79
+
The <parameter>algo</parameter> parameter expects a &string; now, but still accepts
80
+
&integer;s for backward compatibility.
81
+
</entry>
82
+
</row>
83
+
</tbody>
84
+
</tgroup>
85
+
</informaltable>
86
+
</para>
87
+
</refsect1>
88
+
55
89
<refsect1 role="examples">
56
90
&reftitle.examples;
57
91
<para>
...
...
@@ -64,19 +98,21 @@
64
98
$password = 'rasmuslerdorf';
65
99
$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';
66
100
67
-
// The cost parameter can change over time as hardware improves
68
-
$options = array('cost' => 11);
101
+
$algorithm = PASSWORD_BCRYPT;
102
+
// bcrypt's cost parameter can change over time as hardware improves
103
+
$options = ['cost' => 12];
69
104
70
105
// Verify stored hash against plain-text password
71
106
if (password_verify($password, $hash)) {
72
-
// Check if a newer hashing algorithm is available
73
-
// or the cost has changed
74
-
if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
107
+
// Check if either the algorithm or the options have changed
108
+
if (password_needs_rehash($hash, $algorithm, $options)) {
75
109
// If so, create a new hash, and replace the old one
76
-
$newHash = password_hash($password, PASSWORD_DEFAULT, $options);
110
+
$newHash = password_hash($password, $algorithm, $options);
111
+
112
+
// Update the user record with the $newHash
77
113
}
78
114
79
-
// Log user in
115
+
// Perform the login.
80
116
}
81
117
?>
82
118
]]>
...
...
@@ -85,14 +121,6 @@ if (password_verify($password, $hash)) {
85
121
</para>
86
122
</refsect1>
87
123
88
-
<refsect1 role="returnvalues">
89
-
&reftitle.returnvalues;
90
-
<para>
91
-
Returns &true; if the hash should be rehashed to match the given
92
-
<parameter>algo</parameter> and <parameter>options</parameter>, or &false;
93
-
otherwise.
94
-
</para>
95
-
</refsect1>
96
124
</refentry>
97
125
98
126
<!-- Keep this comment at the end of the file
99
127