Add a warning about the subtle global state in legacy random functions

Fixes php/php-src#21351
Replaces php/php-src#21352

Author: anthonyryan1

language-snippets.ent

@@ -31,6 +31,16 @@ highly discouraged.</simpara></warning>'>
  </para>
 </caution>'>
 
+<!ENTITY caution.subtle-global-state '<caution xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+    This function shares a global state with other functions.
+    These functions can alter each other's outputs, regardless of scope.
+  </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

reference/array/functions/array-rand.xml

@@ -17,6 +17,7 @@
    key (or keys) of the random entries.
   </para>
   &caution.cryptographically-insecure;
+  &caution.subtle-global-state;
  </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.subtle-global-state;
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;

reference/random/functions/mt-rand.xml

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

reference/random/functions/mt-srand.xml

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

reference/random/functions/rand.xml

@@ -25,6 +25,7 @@
    15)</literal>.
   </simpara>
   &caution.cryptographically-insecure;
+  &caution.subtle-global-state;
   <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.subtle-global-state;
   <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.subtle-global-state;
  </refsect1>
 
  <refsect1 role="parameters">