[DOC-CVS] [doc-en] master: Add a warning about the subtle global state in legacy random functions (#5414)

Author: Anthony Ryan (anthonyryan1)
Committer: GitHub (web-flow)
Pusher: TimWolla
Date: 2026-03-24T00:23:46+01:00

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

Add a warning about the subtle global state in legacy random functions (#5414)

Fixes https://github.com/php/php-src/issues/21351
Replaces https://github.com/php/php-src/pull/21352

Changed paths:
  M  language-snippets.ent
  M  reference/array/functions/array-rand.xml
  M  reference/array/functions/shuffle.xml
  M  reference/random/functions/mt-rand.xml
  M  reference/random/functions/rand.xml
  M  reference/strings/functions/str-shuffle.xml


Diff:

diff --git a/language-snippets.ent b/language-snippets.ent
index 302a9c81131d..0cd4af3d9e1c 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -31,6 +31,19 @@ highly discouraged.</simpara></warning>'>
  </para>
 </caution>'>
 
+<!ENTITY caution.mt19937-global-state '<caution xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+    This function uses the global Mt19937 (“Mersenne Twister”) instance as the source of randomness and thus shares its state with all other functions using the global Mt19937.
+    Using any of these functions advances the sequence for <emphasis>all</emphasis> the other functions, regardless of scope.
+  </simpara>
+  <simpara>
+    Generating repeatable sequences by seeding <function>mt_srand</function> or <function>srand</function> with a known value will also yield repeatable output from this function.
+  </simpara>
+  <simpara>
+    Prefer using <classname>Random\Randomizer</classname> methods in all newly written code.
+ </simpara>
+</caution>'>
+
 <!ENTITY caution.mt19937-tiny-seed '<caution xmlns="http://docbook.org/ns/docbook">
  <para>
   Because the Mt19937 (“Mersenne Twister”) engine accepts only a single 32 bit integer as the
diff --git a/reference/array/functions/array-rand.xml b/reference/array/functions/array-rand.xml
index 5dad19274d4c..6c2156f9075e 100644
--- a/reference/array/functions/array-rand.xml
+++ b/reference/array/functions/array-rand.xml
@@ -17,6 +17,7 @@
    key (or keys) of the random entries.
   </para>
   &caution.cryptographically-insecure;
+  &caution.mt19937-global-state;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
diff --git a/reference/array/functions/shuffle.xml b/reference/array/functions/shuffle.xml
index 5e24f8943ea5..1d61fcfcfecb 100644
--- a/reference/array/functions/shuffle.xml
+++ b/reference/array/functions/shuffle.xml
@@ -15,6 +15,7 @@
    This function shuffles (randomizes the order of the elements in) an array.
   </para>
   &caution.cryptographically-insecure;
+  &caution.mt19937-global-state;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
diff --git a/reference/random/functions/mt-rand.xml b/reference/random/functions/mt-rand.xml
index b4c3a460c825..f769e8118078 100644
--- a/reference/random/functions/mt-rand.xml
+++ b/reference/random/functions/mt-rand.xml
@@ -35,6 +35,7 @@
    15)</literal>.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-global-state;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
diff --git a/reference/random/functions/rand.xml b/reference/random/functions/rand.xml
index ec55b6bb2f1f..a59edaf5cad3 100644
--- a/reference/random/functions/rand.xml
+++ b/reference/random/functions/rand.xml
@@ -25,6 +25,7 @@
    15)</literal>.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-global-state;
   <note>
    <simpara>
     Prior to PHP 7.1.0, <function>getrandmax</function> was only 32767 on some
diff --git a/reference/strings/functions/str-shuffle.xml b/reference/strings/functions/str-shuffle.xml
index 4d2489c04847..fd2aac6ee4d2 100644
--- a/reference/strings/functions/str-shuffle.xml
+++ b/reference/strings/functions/str-shuffle.xml
@@ -17,6 +17,7 @@
    of all possible is created.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-global-state;
  </refsect1>
 
  <refsect1 role="parameters">