Add example for password_needs_rehash to documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@336027 c90b9560-bf6c-de11-be94-00142212c4b1

reference/password/functions/password-needs-rehash.xml

@@ -51,6 +51,40 @@
    </varlistentry>
   </variablelist>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Example #1 <function>password_needs_rehash()</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$password = 'rasmuslerdorf';
+$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';
+
+// The cost parameter can change over time as hardware improves
+$options = array('cost' => 11);
+
+// Verify stored hash against plain-text password
+if (password_verify($password, $hash)) {
+    // Check if a newer hashing algorithm is available
+    // or the cost has changed
+    if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
+        // If so, create a new hash, and replace the old one
+        $newHash = password_hash($password, PASSWORD_DEFAULT, $options);
+    }
+
+    // Log user in
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+   </example>
+  </para> 
+ </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;