From 2d0885c393eedbab186832899fc49452b528b64b Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Tue, 8 Sep 2026 09:38:21 +0200
Subject: [PATCH] [Sync-En] htmlspecialchars: add the ENT_IGNORE/ENT_SUBSTITUTE
 example with invalid UTF-8 bytes

---
 .../strings/functions/htmlspecialchars.xml    | 37 +++++++++++++++----
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/reference/strings/functions/htmlspecialchars.xml b/reference/strings/functions/htmlspecialchars.xml
index d206b1d43f..34c7d4238d 100644
--- a/reference/strings/functions/htmlspecialchars.xml
+++ b/reference/strings/functions/htmlspecialchars.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: eabde0419cf90f596f60db00e31fcb6ebe41ac55 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: a9d052e2db27dd26e5f77b13ca03f0e9d352db5a Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.htmlspecialchars" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -30,10 +30,10 @@
    preparar la entrada para una inclusión en la mayoría de los contextos
    de un documento HTML. Sin embargo, si la entrada puede presentar caracteres
    que no están codificados en el juego de caracteres del documento final,
-   y se desea preservar estos caracteres (como numéricos o
-   entidades nombradas), esta función y la función <function>htmlentities</function>
+   y se desea preservar estos caracteres (en forma de entidades numéricas o
+   nombradas), esta función y la función <function>htmlentities</function>
    (que solo codifica las subcadenas que tienen entidades nombradas equivalentes)
-   no son suficientes. Se debe utilizar la función
+   pueden no ser suficientes. Puede que sea necesario utilizar la función
    <function>mb_encode_numericentity</function> en su lugar.
   </para>
   <para>
@@ -53,7 +53,7 @@
       </row>
       <row>
        <entry><literal>&quot;</literal> (comillas dobles)</entry>
-       <entry><literal>&amp;quot;</literal> excepto si <constant>ENT_NOQUOTES</constant></entry>
+       <entry><literal>&amp;quot;</literal> excepto si <constant>ENT_NOQUOTES</constant> está definido</entry>
       </row>
       <row>
        <entry><literal>'</literal> (comilla simple)</entry>
@@ -140,8 +140,8 @@
           <row>
            <entry><constant>ENT_DISALLOWED</constant></entry>
            <entry>
-            Reemplaza los puntos de código inválidos del documento proporcionado con
-            un carácter de reemplazo Unicode U+FFFD (UTF-8) o &amp;#xFFFD;
+            Reemplaza los puntos de código inválidos para el tipo de documento
+            proporcionado con un carácter de reemplazo Unicode U+FFFD (UTF-8) o &amp;#xFFFD;
             (de lo contrario) en lugar de dejarlo tal cual. Esto puede ser útil para,
             por ejemplo, asegurar el correcto formato de documentos XML que contienen
             contenido externo.
@@ -200,7 +200,7 @@
      <listitem>
       <para>
        Cuando el parámetro <parameter>double_encode</parameter> está desactivado,
-       PHP no codificará las entidades html existentes; por omisión, todo es convertido.
+       PHP no codificará las entidades HTML existentes; por omisión, todo es convertido.
       </para>
      </listitem>
     </varlistentry>
@@ -256,6 +256,27 @@
 $new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
 echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
 ?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><constant>ENT_IGNORE</constant> y <constant>ENT_SUBSTITUTE</constant> con secuencias UTF-8 inválidas</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// "\x80" no es una secuencia de bytes UTF-8 válida.
+$input = "atta\x80ck";
+
+// ENT_IGNORE descarta silenciosamente el byte inválido - resultado: "attack"
+echo bin2hex(htmlspecialchars($input, ENT_QUOTES | ENT_IGNORE, 'UTF-8')), "\n";
+// 61747461636b
+
+// ENT_SUBSTITUTE reemplaza el byte inválido por U+FFFD - resultado: "atta" + carácter de reemplazo + "ck"
+echo bin2hex(htmlspecialchars($input, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')), "\n";
+// 61747461efbfbd636b
+?>
 ]]>
     </programlisting>
    </example>