From 23cfec39eedfca17f26adeba2a59db0a4795e433 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Thu, 27 Aug 2026 17:47:15 +0200
Subject: [PATCH] [Sync-En] errorfunc: document the error handler stack

---
 .../functions/restore-error-handler.xml       |  40 +++----
 .../errorfunc/functions/set-error-handler.xml | 104 ++++++++++++++----
 2 files changed, 104 insertions(+), 40 deletions(-)

diff --git a/reference/errorfunc/functions/restore-error-handler.xml b/reference/errorfunc/functions/restore-error-handler.xml
index 009f3c216..7a7405849 100644
--- a/reference/errorfunc/functions/restore-error-handler.xml
+++ b/reference/errorfunc/functions/restore-error-handler.xml
@@ -1,8 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- EN-Revision: 4a6671fe697ead5b27603b56face01a2c4e7ebe5 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: no -->
-
+<!-- EN-Revision: cbfc5d5d55d682c185583561295462a6d5ca0ea1 Maintainer: PhilDaiguille Status: ready -->
 <refentry xml:id="function.restore-error-handler" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>restore_error_handler</refname>
@@ -15,13 +12,18 @@
    <type>true</type><methodname>restore_error_handler</methodname>
    <void/>
   </methodsynopsis>
-  <para>
-   Utilizada después de modificar la función de manejo de errores,
-   gracias a <function>set_error_handler</function>,
-   <function>restore_error_handler</function> permite reutilizar
-   la versión anterior de manejo de errores (que puede ser la
-   función PHP por defecto, o alguna otra función del usuario).
-  </para>
+  <simpara>
+   Extrae de la pila interna de gestores de errores el gestor que estaba activo
+   antes de la última llamada a <function>set_error_handler</function> y lo
+   vuelve a activar, junto con la máscara
+   <parameter>error_levels</parameter> con la que fue registrado.
+   El gestor restaurado puede ser el gestor interno o una función definida por
+   el usuario.
+  </simpara>
+  <simpara>
+   Llamar a esta función más veces que a <function>set_error_handler</function>
+   deja activo el gestor de errores interno; no se genera ningún error.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -72,15 +74,13 @@ Valor incorrectamente serializado.
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>error_reporting</function></member>
-    <member><function>set_error_handler</function></member>
-    <member><function>get_error_handler</function></member>
-    <member><function>restore_exception_handler</function></member>
-    <member><function>trigger_error</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>error_reporting</function></member>
+   <member><function>set_error_handler</function></member>
+   <member><function>get_error_handler</function></member>
+   <member><function>restore_exception_handler</function></member>
+   <member><function>trigger_error</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/errorfunc/functions/set-error-handler.xml b/reference/errorfunc/functions/set-error-handler.xml
index b19c2be20..3397c6059 100644
--- a/reference/errorfunc/functions/set-error-handler.xml
+++ b/reference/errorfunc/functions/set-error-handler.xml
@@ -1,7 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!-- EN-Revision: 21ce7d7f4f9f6f241f3e09e7f0a5be5c504d90d2 Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: no -->
+<!-- EN-Revision: cbfc5d5d55d682c185583561295462a6d5ca0ea1 Maintainer: PhilDaiguille Status: ready -->
 <refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>set_error_handler</refname>
@@ -15,10 +13,13 @@
    <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>
   </methodsynopsis>
-  <para>
-   <function>set_error_handler</function> selecciona la función de usuario
-   <parameter>callback</parameter> para gestionar errores en un script.
-  </para>
+  <simpara>
+   Define una función de usuario (<parameter>callback</parameter>) para
+   gestionar los errores de un script.
+   El gestor que estaba activo hasta ese momento se guarda en una pila interna
+   de gestores de errores, de la cual <function>restore_error_handler</function>
+   lo vuelve a extraer.
+  </simpara>
   <para>
    Esta función puede ser utilizada para definir gestores de errores personalizados durante la ejecución,
    por ejemplo en aplicaciones que necesitan limpiar archivos/datos cuando ocurre un error crítico
@@ -65,10 +66,13 @@
     <varlistentry>
      <term><parameter>callback</parameter></term>
      <listitem>
-      <para>
-       Si &null; es proporcionado, el gestor es reestablecido a su estado por defecto.
+      <simpara>
+       Si se proporciona &null;, no queda activo ningún gestor definido por el
+       usuario y los errores vuelven al gestor de errores interno.
+       El gestor que estaba activo hasta ese momento sigue guardado en la pila y
+       puede recuperarse con <function>restore_error_handler</function>.
        De lo contrario, el gestor es una función de retorno con la siguiente firma:
-      </para>
+      </simpara>
       <para>
        <methodsynopsis>
         <type>bool</type><methodname><replaceable>handler</replaceable></methodname>
@@ -335,24 +339,84 @@ vector d - error fatal
 <b>MI ERROR</b> [256] log(x) para x <= 0 es indefinido, usted usó: scale = -2.5<br />
 Error fatal en la línea 36 en el archivo trigger_error.php, PHP 4.0.2 (Linux)<br />
 Abandono...<br />
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Llamada al gestor anterior desde el nuevo</title>
+    <simpara>
+     El valor devuelto por <function>set_error_handler</function> es el gestor
+     que estaba activo hasta ese momento. Llamarlo desde el nuevo gestor
+     conserva el comportamiento existente y le añade el nuevo. Esto solo
+     funciona si ese gestor es una función definida por el usuario; se devuelve
+     &null; cuando el gestor activo era el interno.
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function logging_handler(int $errno, string $errstr): bool
+{
+    echo "registrado: $errstr\n";
+    return true;
+}
+
+set_error_handler('logging_handler');
+
+$previous = set_error_handler(function (int $errno, string $errstr) use (&$previous): bool {
+    echo "contado: $errstr\n";
+    return $previous !== null ? $previous($errno, $errstr) : false;
+});
+
+trigger_error("ha ocurrido algo", E_USER_WARNING);
+
+restore_error_handler();
+trigger_error("ahora solo registrado", E_USER_WARNING);
+
+restore_error_handler();
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+contado: ha ocurrido algo
+registrado: ha ocurrido algo
+registrado: ahora solo registrado
 ]]>
     </screen>
    </example>
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <caution>
+   <simpara>
+    No se debe volver al gestor anterior pasando de nuevo a
+    <function>set_error_handler</function> el valor que esta devolvió.
+    Al hacerlo se añade una entrada más a la pila en lugar de retirar una, por
+    lo que la pila crece sin límite en los bucles y en los procesos de larga
+    duración, y <parameter>error_levels</parameter> se reinicia a
+    <constant>E_ALL</constant>, ampliando de forma silenciosa el rango de
+    errores que recibe el gestor restaurado.
+    <function>restore_error_handler</function> es la forma prevista de volver
+    al gestor anterior.
+   </simpara>
+  </caution>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><classname>ErrorException</classname></member>
-    <member><function>error_reporting</function></member>
-    <member><function>restore_error_handler</function></member>
-    <member><function>get_error_handler</function></member>
-    <member><function>trigger_error</function></member>
-    <member><link linkend="errorfunc.constants">Constantes de nivel de error</link></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><exceptionname>ErrorException</exceptionname></member>
+   <member><function>error_reporting</function></member>
+   <member><function>restore_error_handler</function></member>
+   <member><function>get_error_handler</function></member>
+   <member><function>trigger_error</function></member>
+   <member><link linkend="errorfunc.constants">Constantes de nivel de error</link></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file