Add a warning about the footgun that is combining legacy MT random functions and pcntl_fork

language-snippets.ent

@@ -31,6 +31,28 @@ highly discouraged.</simpara></warning>'>
  </para>
 </caution>'>
 
+<!ENTITY caution.mt19937-fork-unsafe '<caution xmlns="http://docbook.org/ns/docbook">
+ <para>
+    This method uses a lazy-initialized, global Mt19937 state.
+  </para>
+  <para>
+    If your code seeds the Mt19937 engine before <function>pcntl_fork</function>
+    (including indirectly via calls to
+    <function>rand</function>,
+    <function>mt_rand</function>,
+    <function>shuffle</function>,
+    <function>array_rand</function> or
+    <function>str_shuffle</function>),
+    forked children will inherit the parent seed and produce identical sequences.
+  </para>
+  <para>
+    If your code calls <function>pcntl_fork</function> without prior calls, every child will have a unique seed and produce a unique sequence.
+  </para>
+  <para>
+    Prefer using <classname>Random\Randomizer</classname> methods in all newly written code.
+ </para>
+</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

reference/array/functions/array-rand.xml

@@ -17,6 +17,7 @@
    key (or keys) of the random entries.
   </para>
   &caution.cryptographically-insecure;
+  &caution.mt19937-fork-unsafe;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;

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-fork-unsafe;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;

reference/pcntl/functions/pcntl-fork.xml

@@ -62,6 +62,27 @@ if ($pid == -1) {
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <caution>
+   <para>
+    The addition or removal of legacy random functions
+    (<function>srand</function>,
+    <function>mt_srand</function>,
+    <function>rand</function>,
+    <function>mt_rand</function>,
+    <function>shuffle</function>,
+    <function>array_rand</function> or
+    <function>str_shuffle</function>)
+    in any code executed prior to <function>pcntl_fork</function> can drastically
+    alter the behavior of these legacy random functions after forking.
+   </para>
+   <para>
+     Prefer using <classname>Random\Randomizer</classname> methods in all newly written code.
+   </para>
+  </caution>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>

reference/random/functions/mt-rand.xml

@@ -35,6 +35,7 @@
    15)</literal>.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-fork-unsafe;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;

reference/random/functions/mt-srand.xml

@@ -20,6 +20,7 @@
 
   &note.randomseed;
   &caution.mt19937-tiny-seed;
+  &caution.mt19937-fork-unsafe;
 
  </refsect1>
  <refsect1 role="parameters">

reference/random/functions/rand.xml

@@ -25,6 +25,7 @@
    15)</literal>.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-fork-unsafe;
   <note>
    <simpara>
     Prior to PHP 7.1.0, <function>getrandmax</function> was only 32767 on some

reference/random/functions/srand.xml

@@ -20,6 +20,7 @@
 
   &note.randomseed;
   &caution.mt19937-tiny-seed;
+  &caution.mt19937-fork-unsafe;
   <note><simpara>As of PHP 7.1.0, <function>srand</function> has been made
    an alias of <function>mt_srand</function>.</simpara>
   </note>

reference/strings/functions/str-shuffle.xml

@@ -17,6 +17,7 @@
    of all possible is created.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.mt19937-fork-unsafe;
  </refsect1>
 
  <refsect1 role="parameters">