Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TimWolla merged 1 commit into from
Mar 23, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions language-snippets.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions reference/array/functions/array-rand.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions reference/array/functions/shuffle.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
1 change: 1 addition & 0 deletions reference/random/functions/mt-rand.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
15)</literal>.
</simpara>
&caution.cryptographically-insecure;
&caution.mt19937-global-state;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
Expand Down
1 change: 1 addition & 0 deletions reference/random/functions/rand.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions reference/strings/functions/str-shuffle.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
of all possible is created.
</simpara>
&caution.cryptographically-insecure;
&caution.mt19937-global-state;
</refsect1>

<refsect1 role="parameters">
Expand Down