Skip to content

[Sync-En] errorfunc: document the error handler stack #1144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julionc merged 1 commit into from
Aug 28, 2026
+104 −40
Merged

[Sync-En] errorfunc: document the error handler stack #1144

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions reference/errorfunc/functions/restore-error-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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">
Expand Down Expand Up @@ -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
Expand Down
104 changes: 84 additions & 20 deletions reference/errorfunc/functions/set-error-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand Down