[DOC-CVS] [doc-en] master: Clarify Argon2 memory_cost and time_cost units in password_hash() (#5219)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-08-12T18:44:19+02:00

Commit: https://github.com/php/doc-en/commit/6cc48aed6f887bdabf09c568f854099f9c74e017
Raw diff: https://github.com/php/doc-en/commit/6cc48aed6f887bdabf09c568f854099f9c74e017.diff

Clarify Argon2 memory_cost and time_cost units in password_hash() (#5219)

* Clarify Argon2 memory_cost and time_cost units in password_hash()

Changed paths:
  M  reference/password/constants.xml
  M  reference/password/functions/password-hash.xml


Diff:

diff --git a/reference/password/constants.xml b/reference/password/constants.xml
index c5d53d31df0d..73879fd2a55e 100644
--- a/reference/password/constants.xml
+++ b/reference/password/constants.xml
@@ -56,10 +56,13 @@
      (<type>int</type>)
     </term>
     <listitem>
-     <para>
-     </para>
-     <para>
-     </para>
+     <simpara>
+      Default algorithmic cost used by <function>password_hash</function> when
+      hashing passwords with <constant>PASSWORD_BCRYPT</constant>.
+     </simpara>
+     <simpara>
+      Available as of PHP 7.0.0.
+     </simpara>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="constant.password-argon2i">
@@ -83,10 +86,10 @@
        </para>
       </listitem>
       <listitem>
-       <para>
-        <literal>time_cost</literal> (<type>int</type>) - Maximum amount of time it may
-        take to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
-       </para>
+       <simpara>
+        <literal>time_cost</literal> (<type>int</type>) - Number of iterations (passes) used
+        to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
+       </simpara>
       </listitem>
       <listitem>
        <para>
@@ -123,13 +126,13 @@
      (<type>int</type>)
     </term>
     <listitem>
-     <para>
-      Default amount of memory in bytes that will be used while trying to
-      compute a hash.
-     </para>
-     <para>
+     <simpara>
+      Default amount of memory in kibibytes (KiB) that will be used
+      to compute a hash.
+     </simpara>
+     <simpara>
       Available as of PHP 7.2.0.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="constant.password-argon2-default-time-cost">
@@ -138,12 +141,12 @@
      (<type>int</type>)
     </term>
     <listitem>
-     <para>
-      Default amount of time that will be spent trying to compute a hash.
-     </para>
-     <para>
+     <simpara>
+      Default number of iterations (passes) used to compute a hash.
+     </simpara>
+     <simpara>
       Available as of PHP 7.2.0.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="constant.password-argon2-default-threads">
diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml
index eacf35cf798c..d7ee2a007b31 100644
--- a/reference/password/functions/password-hash.xml
+++ b/reference/password/functions/password-hash.xml
@@ -100,10 +100,10 @@
      </para>
     </listitem>
     <listitem>
-     <para>
-      <literal>time_cost</literal> (<type>int</type>) - Maximum amount of time it may 
-      take to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
-     </para>
+     <simpara>
+      <literal>time_cost</literal> (<type>int</type>) - Number of iterations (passes)
+      used to compute the Argon2 hash. Defaults to <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
+     </simpara>
     </listitem>
     <listitem>
      <para>