[doc-en] master: Fix outdated string to number comparison rules in min() and max() (#5914)

Author: Zotis Angelis (angeliszotis) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-07T12:28:14+02:00 Commit: https://github.com/php/doc-en/commit/9b77252fe6d218efb8921e3cc4a1abc948fd7c39 Raw diff: https://github.com/php/doc-en/commit/9b77252fe6d218efb8921e3cc4a1abc948fd7c39.diff Fix outdated string to number comparison rules in min() and max() (#5914) * Fix outdated string to number comparison rules in min() and max() Both pages still describe the comparison semantics from before PHP 8.0. I checked every claim and every example on PHP 8.4.26, these are the ones that no longer hold: The note in the description says a non-numeric string is compared to an int "as though it were 0". Since PHP 8.0 it is the other way around, the int is cast to string and the comparison is done as strings. The return values section uses 0 and 'abc' as an example of two values of different types that evaluate as equal. In PHP 8, 0 == 'abc' is false. Replaced with 0 and false, which is still true, and the order still decides which one is returned. The 'hello' example explains the result with "comparing -1 < 0". The result is still 'hello' but for a different reason, -1 becomes the string "-1" and "hello" is greater than it as a string. In min(), the documented output of min('string', array(2, 5, 7), 42) is 'string'. It returns 42 now, because 42 is compared with 'string' as the string "42", and "42" is lower than "string". The changelog on both pages already mentions that string to number comparisons changed in 8.0, so the pages contradict themselves. Fixes #2687 * min()/max(): use simpara for inline-only paragraphs The DocBook style check flagged the note and return-value paragraphs. Changed paths: M reference/math/functions/max.xml M reference/math/functions/min.xml Diff: diff --git a/reference/math/functions/max.xml b/reference/math/functions/max.xml index 2dd7e3c7896d..8b0eebacd2a1 100644 --- a/reference/math/functions/max.xml +++ b/reference/math/functions/max.xml @@ -23,13 +23,14 @@ provided, <function>max</function> returns the biggest of these values. </para> <note> - <para> + <simpara> Values of different types will be compared using the <link linkend="language.operators.comparison"> - standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be - compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric - <type>string</type> values will be compared alphanumerically. The actual value returned will be of the - original type with no conversion applied. - </para> + standard comparison rules</link>. For instance, when a non-numeric <type>string</type> is + compared to an <type>int</type>, the <type>int</type> is cast to <type>string</type> and the + values are compared as strings; before PHP 8.0.0 the <type>string</type> was cast to + <type>int</type> instead. Multiple non-numeric <type>string</type> values are also compared as + strings. The actual value returned will be of the original type with no conversion applied. + </simpara> </note> <caution> <simpara> @@ -73,11 +74,11 @@ </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> <function>max</function> returns the parameter value considered "highest" according to standard comparisons. If multiple values of different types evaluate as equal (e.g. <literal>0</literal> - and <literal>'abc'</literal>) the first provided to the function will be returned. - </para> + and &false;) the first provided to the function will be returned. + </simpara> </refsect1> <refsect1 role="errors"> @@ -130,7 +131,8 @@ echo max(2, 3, 1, 6, 7), PHP_EOL; // 7 echo max(array(2, 4, 5)), PHP_EOL; // 5 -// Here we are comparing -1 < 0, so 'hello' is the highest value +// 'hello' is a non-numeric string, so -1 is cast to the string "-1" and the +// values are compared as strings: "hello" is greater than "-1" echo max('hello', -1), PHP_EOL; // hello // With multiple arrays of different lengths, max returns the longest diff --git a/reference/math/functions/min.xml b/reference/math/functions/min.xml index c440f4c2dc12..14baec6ff2b8 100644 --- a/reference/math/functions/min.xml +++ b/reference/math/functions/min.xml @@ -23,13 +23,14 @@ provided, <function>min</function> returns the smallest of these values. </para> <note> - <para> + <simpara> Values of different types will be compared using the <link linkend="language.operators.comparison"> - standard comparison rules</link>. For instance, a non-numeric <type>string</type> will be - compared to an <type>int</type> as though it were <literal>0</literal>, but multiple non-numeric - <type>string</type> values will be compared alphanumerically. The actual value returned will be of the - original type with no conversion applied. - </para> + standard comparison rules</link>. For instance, when a non-numeric <type>string</type> is + compared to an <type>int</type>, the <type>int</type> is cast to <type>string</type> and the + values are compared as strings; before PHP 8.0.0 the <type>string</type> was cast to + <type>int</type> instead. Multiple non-numeric <type>string</type> values are also compared as + strings. The actual value returned will be of the original type with no conversion applied. + </simpara> </note> <caution> <simpara> @@ -73,11 +74,11 @@ </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; - <para> + <simpara> <function>min</function> returns the parameter value considered "lowest" according to standard comparisons. If multiple values of different types evaluate as equal (e.g. <literal>0</literal> - and <literal>'abc'</literal>) the first provided to the function will be returned. - </para> + and &false;) the first provided to the function will be returned. + </simpara> </refsect1> <refsect1 role="errors"> @@ -130,7 +131,8 @@ echo min(2, 3, 1, 6, 7), PHP_EOL; // 1 echo min(array(2, 4, 5)), PHP_EOL; // 2 -// Here we are comparing -1 < 0, so -1 is the lowest value +// 'hello' is a non-numeric string, so -1 is cast to the string "-1" and the +// values are compared as strings: "-1" is lower than "hello" echo min('hello', -1), PHP_EOL; // -1 // With multiple arrays of different lengths, min returns the shortest @@ -144,7 +146,9 @@ var_dump($val); // If both an array and non-array are given, the array is never returned // as comparisons treat arrays as greater than any other value -$val = min('string', array(2, 5, 7), 42); // string +// Of the remaining values, 42 is cast to the string "42" when compared with the +// non-numeric string 'string', and "42" is lower than "string" +$val = min('string', array(2, 5, 7), 42); // 42 var_dump($val); // If one argument is NULL or a boolean, it will be compared against