php · Girgias · Nov 7, 2022 · Nov 3, 2022 · Nov 4, 2022 · Nov 7, 2022
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -28,11 +28,6 @@ cryptographically secure value, consider using <function>random_int</function>,
 <!ENTITY note.bin-safe '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is
 binary-safe.</simpara></note>'>
 
-<!ENTITY note.locale-single-byte '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function is locale-aware
-and will handle input according to the currently set locale.  However, it only works on single-byte character sets.
-If you need to use multibyte characters (most non-western-European languages) look at the
-<link linkend="book.mbstring">multibyte</link> or <link linkend="book.intl">intl</link> extensions instead.</simpara></note>'>
-
 <!ENTITY note.clearstatcache '<note xmlns="http://docbook.org/ns/docbook"><simpara>The results of this
 function are cached. See <function>clearstatcache</function> for
 more details.</simpara></note>'>
@@ -3696,6 +3691,27 @@ local: {
  </row>
 '>
 
+<!ENTITY strings.changelog.ascii-case-conversion '
+ <row xmlns="http://docbook.org/ns/docbook">
+  <entry>8.2.0</entry>
+  <entry>
+   Case conversion no longer depends on the locale set with
+   <function>setlocale</function>. Only ASCII characters will be converted.
+  </entry>
+ </row>
+'>
+
+<!ENTITY strings.changelog.ascii-case-folding '
+ <row xmlns="http://docbook.org/ns/docbook">
+  <entry>8.2.0</entry>
+  <entry>
+   Case folding no longer depends on the locale set with
+   <function>setlocale</function>. Only ASCII case folding will be done.
+   Non-ASCII bytes will be compared by their byte value.
+  </entry>
+ </row>
+'>
+
 <!-- filter snippets -->
 <!ENTITY filter.param.filter '
  <varlistentry xmlns="http://docbook.org/ns/docbook">

diff --git a/reference/array/constants.xml b/reference/array/constants.xml
@@ -15,7 +15,8 @@
      <constant>CASE_LOWER</constant> is used with
      <function>array_change_key_case</function> and is used to convert array
      keys to lower case. This is also the default case for
-     <function>array_change_key_case</function>.
+     <function>array_change_key_case</function>. As of PHP 8.2.0, only ASCII
+     characters will be converted.
     </simpara>
    </listitem>
   </varlistentry>
@@ -28,7 +29,8 @@
     <simpara>
      <constant>CASE_UPPER</constant> is used with
      <function>array_change_key_case</function> and is used to convert array
-     keys to upper case.
+     keys to upper case. As of PHP 8.2.0, only ASCII characters will be
+     converted.
     </simpara>
    </listitem>
   </varlistentry>
@@ -130,10 +132,10 @@
    </term>
    <listitem>
     <simpara>
-    <constant>SORT_FLAG_CASE</constant> can be combined
-         (bitwise OR) with
-         <constant>SORT_STRING</constant> or
-         <constant>SORT_NATURAL</constant> to sort strings case-insensitively.
+     <constant>SORT_FLAG_CASE</constant> can be combined (bitwise OR) with
+     <constant>SORT_STRING</constant> or <constant>SORT_NATURAL</constant> to
+     sort strings case-insensitively. As of PHP 8.2.0, only ASCII case folding
+     will be done.
     </simpara>
    </listitem>
   </varlistentry>

diff --git a/reference/strings/functions/lcfirst.xml b/reference/strings/functions/lcfirst.xml
@@ -15,12 +15,8 @@
   <para>
    Returns a string with the first character of
    <parameter>string</parameter> lowercased if that character is
-   alphabetic.
-  </para>
-  <para>
-   Note that 'alphabetic' is determined by the current locale. For
-   instance, in the default "C" locale characters such as umlaut-a
-   (ä) will not be converted.
+   an ASCII character in the range <literal>"A"</literal> (0x41) to
+   <literal>"Z"</literal> (0x5a).
   </para>
  </refsect1>
 
@@ -47,6 +43,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-conversion;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>

diff --git a/reference/strings/functions/setlocale.xml b/reference/strings/functions/setlocale.xml
@@ -62,7 +62,7 @@
         <listitem>
          <simpara>
           <constant>LC_CTYPE</constant> for character classification and conversion, for
-          example <function>strtoupper</function>
+          example <function>ctype_alpha</function>
          </simpara>
         </listitem>
         <listitem>

diff --git a/reference/strings/functions/str-ireplace.xml b/reference/strings/functions/str-ireplace.xml
@@ -97,6 +97,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-folding;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>

diff --git a/reference/strings/functions/stripos.xml b/reference/strings/functions/stripos.xml
@@ -84,6 +84,7 @@
      </row>
     </thead>
     <tbody>
+     &strings.changelog.ascii-case-folding;
      <row>
       <entry>8.0.0</entry>
       <entry>

diff --git a/reference/strings/functions/stristr.xml b/reference/strings/functions/stristr.xml
@@ -76,6 +76,7 @@
       </row>
      </thead>
      <tbody>
+      &strings.changelog.ascii-case-folding;
       <row>
        <entry>8.0.0</entry>
        <entry>

diff --git a/reference/strings/functions/strripos.xml b/reference/strings/functions/strripos.xml
@@ -98,6 +98,7 @@
      </row>
     </thead>
     <tbody>
+     &strings.changelog.ascii-case-folding;
      <row>
       <entry>8.0.0</entry>
       <entry>

diff --git a/reference/strings/functions/strtolower.xml b/reference/strings/functions/strtolower.xml
@@ -13,13 +13,18 @@
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Returns <parameter>string</parameter> with all alphabetic characters
+   Returns <parameter>string</parameter> with all ASCII alphabetic characters
    converted to lowercase.
   </para>
   <para>
-   Note that 'alphabetic' is determined by the current locale. This means
-   that e.g. in the default "C" locale, characters such as umlaut-A
-   (Ä) will not be converted.
+   Bytes in the range <literal>"A"</literal> (0x41) to <literal>"Z"</literal>
+   (0x5a) will be converted to the corresponding lowercase letter by adding 32
+   to each byte value.
+  </para>
+  <para>
+   This can be used to convert ASCII characters within strings encoded with
+   UTF-8, since multibyte UTF-8 characters will be ignored. To convert multibyte
+   non-ASCII characters, use <function>mb_strtolower</function>.
   </para>
  </refsect1>
 
@@ -46,6 +51,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-conversion;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>

diff --git a/reference/strings/functions/strtoupper.xml b/reference/strings/functions/strtoupper.xml
@@ -13,13 +13,18 @@
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Returns <parameter>string</parameter> with all alphabetic characters
+   Returns <parameter>string</parameter> with all ASCII alphabetic characters
    converted to uppercase.
   </para>
   <para>
-   Note that 'alphabetic' is determined by the current locale. For instance,
-   in the default "C" locale characters such as umlaut-a (ä) will not be
-   converted.
+   Bytes in the range <literal>"a"</literal> (0x61) to <literal>"z"</literal>
+   (0x7a) will be converted to the corresponding uppercase letter by subtracting
+   32 from each byte value.
+  </para>
+  <para>
+   This can be used to convert ASCII characters within strings encoded with
+   UTF-8, since multibyte UTF-8 characters will be ignored. To convert multibyte
+   non-ASCII characters, use <function>mb_strtoupper</function>.
   </para>
  </refsect1>
 
@@ -46,6 +51,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-conversion;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>

diff --git a/reference/strings/functions/ucfirst.xml b/reference/strings/functions/ucfirst.xml
@@ -15,12 +15,8 @@
   <para>
    Returns a string with the first character of
    <parameter>string</parameter> capitalized, if that character is
-   alphabetic.
-  </para>
-  <para>
-   Note that 'alphabetic' is determined by the current locale. For
-   instance, in the default "C" locale characters such as umlaut-a
-   (ä) will not be converted.
+   an ASCII character in the range from <literal>"a"</literal> (0x61) to
+   <literal>"z"</literal> (0x7a).
   </para>
  </refsect1>
 
@@ -47,6 +43,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-conversion;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
@@ -76,6 +89,7 @@ $bar = ucfirst(strtolower($bar)); // Hello world!
     <member><function>strtolower</function></member>
     <member><function>strtoupper</function></member>
     <member><function>ucwords</function></member>
+    <member><function>mb_convert_case</function></member>
    </simplelist>
   </para>
  </refsect1>

diff --git a/reference/strings/functions/ucwords.xml b/reference/strings/functions/ucwords.xml
@@ -15,13 +15,20 @@
   </methodsynopsis>
   <para>
    Returns a string with the first character of each word in
-   <parameter>string</parameter> capitalized, if that character is alphabetic.
+   <parameter>string</parameter> capitalized, if that character is an ASCII
+   character between <literal>"a"</literal> (0x61) and <literal>"z"</literal>
+   (0x7a).
   </para>
   <para>
    For this function, a word is a string of characters that are not listed in 
    the <parameter>separators</parameter> parameter. By default, these are: 
    space, horizontal tab, carriage return, newline, form-feed and vertical tab.
   </para>
+  <para>
+   To do a similar conversion on multibyte strings, use
+   <function>mb_convert_case</function> with the <constant>MB_CASE_TITLE</constant>
+   mode.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -55,6 +62,23 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     &strings.changelog.ascii-case-conversion;
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
@@ -110,7 +134,6 @@ $baz = ucwords($foo, " \t\r\n\f\v'"); // Mike O'Hara
 
  <refsect1 role="notes">
   &reftitle.notes;
-  &note.locale-single-byte;
   &note.bin-safe;
  </refsect1>
-Original file line number
+Diff line change
@@ Expand Up / @@ -84,6 +84,7 @@ @@
          </row>
         </thead>
         <tbody>
+         &strings.changelog.ascii-case-folding;
          <row>
           <entry>8.0.0</entry>
           <entry>
@@ Expand Down @@