diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml
index 24bd7678d3..44ebb5f58e 100644
--- a/reference/password/functions/password-hash.xml
+++ b/reference/password/functions/password-hash.xml
@@ -16,7 +16,31 @@
arrayoptions
- password_hash creates a new password hash.
+ password_hash creates a new password hash using a strong one-way hashing
+ algorithm.
+
+
+ The following algorithms are currently supported:
+
+
+
+
+
+ PASSWORD_DEFAULT - Use the bcrypt algorithm (default as of PHP 5.5.0).
+ Note that this constant is designed to change over time as new and stronger algorithms are added
+ to PHP. For that reason, the length of the result from using this identifier can change over
+ time. Therefore, it is recommended to store the result in a database column that can expand
+ beyond 60 characters (255 characters would be a good choice).
+
+
+
+
+ PASSWORD_BCRYPT - Use the CRYPT_BLOWFISH algorithm to
+ create the hash. This will produce a standard crypt compatible hash using
+ the "$2y$" identifier. The result will always be a 60 character string, &return.falseforfailure;.
+
+
+
@@ -88,6 +112,120 @@ $2y$07$BCryptRequires22Chrcte/VlQH0piJtjXl.0t1XkA8pw9dMXTpOq
+
+
+ <function>password_hash</function> example setting cost manually
+
+ 12,
+];
+echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options)."\n";
+?>
+]]>
+
+ &example.outputs;
+
+
+
+
+
+
+
+
+ <function>password_hash</function> example setting salt manually
+
+ 11,
+ 'salt' => mcrypt_create_iv(22, MCRYPT_DEV_URANDOM),
+];
+echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options)."\n";
+?>
+]]>
+
+ &example.outputs;
+
+
+
+
+
+
+
+ <function>password_hash</function> example finding a good cost
+
+ $cost]);
+ $end = microtime(true);
+} while (($end - $start) < 0.2);
+
+echo "Appropriate Cost Found: " . $cost . "\n";
+?>
+]]>
+
+ &example.outputs;
+
+
+
+
+
+
+
+
+ &reftitle.notes;
+
+
+ It is strongly recommended that you do not generate your own salt for this function.
+ It will create a secure salt automatically for you if you do not specify one.
+
+
+
+
+ It is recommended that you should test this function on your servers, and adjust the cost
+ parameter so that execution of the function takes approximately 0.1 to 0.5 seconds. The script
+ in the above example will help you choose a good cost value for your hardware.
+
+
+
+
+ Updates to supported algorithms by this function (or changes to the default one) must follow
+ the follwoing rules:
+
+
+
+
+ Any new algorithm must be in core for at least 1 full release of PHP prior to becoming
+ default. So if, for example, a new algorithm is added in 5.5.5, it would not be eligible for
+ default until 5.7 (since 5.6 would be the first full release). But if a different algorithm was
+ added in 5.6.0, it would also be eligible for default at 5.7.0.
+
+
+
+
+ The default should only change on a full release (5.6.0, 6.0.0, etc) and not on a revision release.
+ The only exception to this is in an emergency when a critical security flaw is found in the current
+ default.
+
+
+
+
+