[DOC-CVS] [doc-en] master: fix(mb-strlen): document invalid encoding ValueError and add shared snippets (#5418)

Author: Gabriel Cordeiro Barroso Teles (GabrielCordeiroBarrosoTeles)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-27T14:56:59+02:00

Commit: https://github.com/php/doc-en/commit/8465ca6ec4bbcf79583ecd057860164dd9c7e385
Raw diff: https://github.com/php/doc-en/commit/8465ca6ec4bbcf79583ecd057860164dd9c7e385.diff

fix(mb-strlen): document invalid encoding ValueError and add shared snippets (#5418)

- Add mbstring.errors.encoding-invalid and mbstring.changelog.encoding-invalid
  entities to language-snippets.ent for consistent documentation
- Use these entities in mb_strlen, mb_internal_encoding, and mb_encoding_aliases,
  replacing per-function custom prose and fixing classname -> exceptionname
- Document that passing an invalid encoding to mb_strlen now throws a ValueError
  as of PHP 8.0.0; previously an E_WARNING was emitted and false was returned

Fixes GH-1132

Co-authored-by: lcatoire <[email protected]>

Changed paths:
  M  language-snippets.ent
  M  reference/mbstring/functions/mb-encoding-aliases.xml
  M  reference/mbstring/functions/mb-internal-encoding.xml
  M  reference/mbstring/functions/mb-strlen.xml


Diff:

diff --git a/language-snippets.ent b/language-snippets.ent
index 26c58a4a886a..af13539e983a 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1201,6 +1201,22 @@ encoding value will be used.</simpara>'>
  </entry>
 </row>'>
 
+<!ENTITY mbstring.errors.encoding-invalid '<para xmlns="http://docbook.org/ns/docbook">
+ As of PHP 8.0.0, a <exceptionname>ValueError</exceptionname> is thrown if
+ <parameter>encoding</parameter> is an invalid encoding.
+ Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was emitted instead.
+</para>'>
+
+<!ENTITY mbstring.changelog.encoding-invalid '<row xmlns="http://docbook.org/ns/docbook">
+ <entry>8.0.0</entry>
+ <entry>
+  Now throws a <exceptionname>ValueError</exceptionname> if
+  <parameter>encoding</parameter> is an invalid encoding.
+  Previously, an <constant>E_WARNING</constant> was emitted
+  and &false; was returned.
+ </entry>
+</row>'>
+
 <!-- mcrypt notes -->
 
 <!ENTITY mcrypt.parameter.cipher '<simpara xmlns="http://docbook.org/ns/docbook">One of the <constant>MCRYPT_ciphername</constant> constants, or the name of the algorithm as string.</simpara>'>
diff --git a/reference/mbstring/functions/mb-encoding-aliases.xml b/reference/mbstring/functions/mb-encoding-aliases.xml
index 77795456657d..99cc406c285b 100644
--- a/reference/mbstring/functions/mb-encoding-aliases.xml
+++ b/reference/mbstring/functions/mb-encoding-aliases.xml
@@ -40,10 +40,7 @@
 
  <refsect1 role="errors">
   &reftitle.errors;
-  <para>
-   Throws a <classname>ValueError</classname> if
-   <parameter>encoding</parameter> is unknown.
-  </para>
+  &mbstring.errors.encoding-invalid;
  </refsect1>
 
  <refsect1 role="changelog">
@@ -57,14 +54,7 @@
      </row>
     </thead>
     <tbody>
-     <row>
-      <entry>8.0.0</entry>
-      <entry>
-       If the <parameter>encoding</parameter> is unknown, a <classname>ValueError</classname>
-       is now thrown; previously an <constant>E_WARNING</constant> was emitted,
-       and the function returned &false;.
-      </entry>
-     </row>
+     &mbstring.changelog.encoding-invalid;
     </tbody>
    </tgroup>
   </informaltable>
diff --git a/reference/mbstring/functions/mb-internal-encoding.xml b/reference/mbstring/functions/mb-internal-encoding.xml
index 00261a2402ba..003460b3e78d 100644
--- a/reference/mbstring/functions/mb-internal-encoding.xml
+++ b/reference/mbstring/functions/mb-internal-encoding.xml
@@ -50,11 +50,7 @@
 
  <refsect1 role="errors">
   &reftitle.errors;
-  <para>
-   As of PHP 8.0.0, a <classname>ValueError</classname> is thrown if the
-   value of <parameter>encoding</parameter> is an invalid encoding.
-   Prior to PHP 8.0.0, a <constant>E_WARNING</constant> was emitted instead.
-  </para>
+  &mbstring.errors.encoding-invalid;
  </refsect1>
 
  <refsect1 role="changelog">
@@ -69,14 +65,7 @@
     </thead>
     <tbody>
      &mbstring.changelog.encoding-nullable;
-     <row>
-      <entry>8.0.0</entry>
-      <entry>
-       Now throws a <classname>ValueError</classname> if
-       <parameter>encoding</parameter> is an invalid encoding.
-       Previously a <constant>E_WARNING</constant> was emitted instead.
-      </entry>
-     </row>
+     &mbstring.changelog.encoding-invalid;
     </tbody>
    </tgroup>
   </informaltable>
diff --git a/reference/mbstring/functions/mb-strlen.xml b/reference/mbstring/functions/mb-strlen.xml
index 45ffabd45f0b..2c1cf73c1fb2 100644
--- a/reference/mbstring/functions/mb-strlen.xml
+++ b/reference/mbstring/functions/mb-strlen.xml
@@ -52,10 +52,7 @@
 
  <refsect1 role="errors">
   &reftitle.errors;
-  <para>
-   If the encoding is unknown, an error of level
-   <constant>E_WARNING</constant> is generated.
-  </para>
+  &mbstring.errors.encoding-invalid;
  </refsect1>
 
  <refsect1 role="changelog">
@@ -70,6 +67,7 @@
     </thead>
     <tbody>
      &mbstring.changelog.encoding-nullable;
+     &mbstring.changelog.encoding-invalid;
     </tbody>
    </tgroup>
   </informaltable>