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 <la.catoire@gmail.com>

Author: GabrielCordeiroBarrosoTeles

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>'>

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>

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>

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>