From 0ec948b40a70214f626d40321d25fe7069f6d2bf Mon Sep 17 00:00:00 2001
From: Louis-Arnaud <la.catoire@gmail.com>
Date: Thu, 3 Sep 2026 13:40:38 +0200
Subject: [PATCH] [Sync-En] ext/mbstring: clarify the ValueError conditions of
 mb_*code_numericentity

---
 .../functions/mb-decode-numericentity.xml     | 127 ++++++++++--------
 .../functions/mb-encode-numericentity.xml     |  26 ++--
 2 files changed, 84 insertions(+), 69 deletions(-)

diff --git a/reference/mbstring/functions/mb-decode-numericentity.xml b/reference/mbstring/functions/mb-decode-numericentity.xml
index 9fe776c671..b26f0d1bdf 100644
--- a/reference/mbstring/functions/mb-decode-numericentity.xml
+++ b/reference/mbstring/functions/mb-decode-numericentity.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 4e69a9f2b14deefca0befec576335e33152448f3 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0bb8d1a0dda028c1086f07dbae25d320850d7a90 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.mb-decode-numericentity" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -63,7 +63,8 @@
   &reftitle.errors;
   <simpara>
    Genera una excepción <exceptionname>ValueError</exceptionname> si
-   <parameter>map</parameter> no es una lista de &integer;s.
+   <parameter>map</parameter> contiene algún valor que no sea un
+   &integer;, un &float;, un &boolean;, &null; o una <link linkend="language.types.numeric-strings">cadena numérica</link>.
   </simpara>
  </refsect1>
 
@@ -81,9 +82,9 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       <function>mb_decode_numericentity</function> ahora genera una
+       La función <function>mb_decode_numericentity</function> ahora genera una
        <exceptionname>ValueError</exceptionname> si <parameter>map</parameter>
-       no es una lista de &integer;s.
+       contiene algún valor que no pueda convertirse implícitamente a int.
       </entry>
      </row>
      &mbstring.changelog.encoding-nullable;
@@ -100,11 +101,13 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$convmap = array (
-   int start_code1, int end_code1, int offset1, int mask1,
-   int start_code2, int end_code2, int offset2, int mask2,
-   // ........
-   int start_codeN, int end_codeN, int offsetN, int maskN );
+
+$convmap = array(
+    int start_code1, int end_code1, int offset1, int mask1,
+    int start_code2, int end_code2, int offset2, int mask2,
+    // ........
+    int start_codeN, int end_codeN, int offsetN, int maskN
+);
 // Especificar valor Unicode para start_codeN y end_codeN
 // Añadir offsetN al valor y realizar 'AND' a nivel de bits con maskN,
 // luego convertir el valor a referencia numérica de cadena.
@@ -120,64 +123,72 @@ $convmap = array (
     <programlisting role="php">
 <![CDATA[
 <?php
-function escape_javascript_string($str) {
-  $map = [
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,0,0, // 49
-          0,0,0,0,0,0,0,0,1,1,
-          1,1,1,1,1,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,1,1,1,1,1,1,0,0,0, // 99
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 149
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 199
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 249
-          1,1,1,1,1,1,1, // 255
-          ];
-  // Codificación de caracteres es UTF-8
-  $mblen = mb_strlen($str, 'UTF-8');
-  $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
-  for ($i=0, $encoded=''; $i < $mblen; $i++) {
-      $u = substr($utf32, $i*8, 8);
-      $v = base_convert($u, 16, 10);
-      if ($v < 256 && $map[$v]) {
-        $encoded .= '\\x'.substr($u, 6,2);
-      } else if ($v == 2028) {
-        $encoded .= '\\u2028';
-      } else if ($v == 2029) {
-        $encoded .= '\\u2029';
-      } else {
-        $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
-      }
-   }
-   return $encoded;
+
+function escape_javascript_string($str)
+{
+    $map = [
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,0,0, // 49
+        0,0,0,0,0,0,0,0,1,1,
+        1,1,1,1,1,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,1,1,1,1,1,1,0,0,0, // 99
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 149
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 199
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 249
+        1,1,1,1,1,1,1, // 255
+    ];
+
+    // La codificación de caracteres es UTF-8
+    $mblen = mb_strlen($str, 'UTF-8');
+    $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
+
+    for ($i=0, $encoded=''; $i < $mblen; $i++) {
+        $u = substr($utf32, $i * 8, 8);
+        $v = base_convert($u, 16, 10);
+
+        if ($v < 256 && $map[$v]) {
+            $encoded .= '\\x' . substr($u, 6,2);
+        } else if ($v == 2028) {
+            $encoded .= '\\u2028';
+        } else if ($v == 2029) {
+            $encoded .= '\\u2029';
+        } else {
+            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
+        }
+    }
+
+    return $encoded;
 }
 
-  // Datos de prueba
+// Datos de prueba
 $convmap = [ 0x0, 0xffff, 0, 0xffff ];
 $msg = '';
+
 for ($i=0; $i < 1000; $i++) {
-  // chr() no puede generar datos UTF-8 correctos mayores que 128, usar mb_decode_numericentity().
-  $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
+  // chr() no puede generar datos UTF-8 correctos con un valor mayor que 128, usar mb_decode_numericentity().
+  $msg .= mb_decode_numericentity('&#' . $i . ';', $convmap, 'UTF-8');
 }
 
 // var_dump($msg);
 var_dump(escape_javascript_string($msg));
+?>
 ]]>
     </programlisting>
    </example>
diff --git a/reference/mbstring/functions/mb-encode-numericentity.xml b/reference/mbstring/functions/mb-encode-numericentity.xml
index dd423dc56e..70676d9e3e 100644
--- a/reference/mbstring/functions/mb-encode-numericentity.xml
+++ b/reference/mbstring/functions/mb-encode-numericentity.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: a60ef65239113c7871643be68ada91081376c936 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0bb8d1a0dda028c1086f07dbae25d320850d7a90 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.mb-encode-numericentity" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -74,7 +74,8 @@
   &reftitle.errors;
   <simpara>
    Lanza una <exceptionname>ValueError</exceptionname> si
-   <parameter>map</parameter> no es una lista de &integer;s.
+   <parameter>map</parameter> contiene algún valor que no sea un
+   &integer;, un &float;, un &boolean;, &null; o una <link linkend="language.types.numeric-strings">cadena numérica</link>.
   </simpara>
  </refsect1>
 
@@ -92,9 +93,9 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       <function>mb_encode_numericentity</function> ahora lanza una
+       La función <function>mb_encode_numericentity</function> ahora lanza una
        <exceptionname>ValueError</exceptionname> si <parameter>map</parameter>
-       no es una lista de &integer;s.
+       contiene algún valor que no pueda convertirse implícitamente a int.
       </entry>
      </row>
      &mbstring.changelog.encoding-nullable;
@@ -111,14 +112,16 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$convmap = array (
- int start_code1, int end_code1, int offset1, int mask1,
- int start_code2, int end_code2, int offset2, int mask2,
- ........
- int start_codeN, int end_codeN, int offsetN, int maskN );
+
+$convmap = array(
+    int start_code1, int end_code1, int offset1, int mask1,
+    int start_code2, int end_code2, int offset2, int mask2,
+    // ........
+    int start_codeN, int end_codeN, int offsetN, int maskN
+);
 // Especificar valor Unicode para start_codeN y end_codeN
-// Añadir offsetN al valor y hacer un 'AND' a nivel de bits con maskN, luego
-// convierte el valor a referencia numérica de string.
+// Añadir offsetN al valor y hacer un 'AND' a nivel de bits con maskN,
+// luego convertir el valor a referencia numérica de string.
 ?>
 ]]>
     </programlisting>
@@ -143,6 +146,7 @@ $convmap = [
     0x80, 0x7FF, 0, 0x10FFFF,
     0x10000, 0x1FFFFF, 0, 0x10FFFF,
 ];
+
 var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
 ?>
 ]]>