Skip to content

errorfunc: document the error handler stack #5253

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
lacatoire merged 1 commit into from
Aug 25, 2026
+100 −31
Merged

errorfunc: document the error handler stack #5253

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
32 changes: 18 additions & 14 deletions reference/errorfunc/functions/restore-error-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,17 @@
<type>true</type><methodname>restore_error_handler</methodname>
<void/>
</methodsynopsis>
<para>
Used after changing the error handler function using
<function>set_error_handler</function>, to revert to the previous error
handler (which could be the built-in or a user defined function).
</para>
<simpara>
Pops the error handler that was active before the most recent call to
<function>set_error_handler</function> off the internal stack of error
handlers and makes it active again, together with the
<parameter>error_levels</parameter> mask it was registered with.
The restored handler could be the built-in or a user defined function.
</simpara>
<simpara>
Calling this function more often than <function>set_error_handler</function>
leaves the built-in error handler active; no error is raised.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand Down Expand Up @@ -67,15 +73,13 @@ Invalid serialized value.

<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
99 changes: 82 additions & 17 deletions reference/errorfunc/functions/set-error-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,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>
Sets a user function (<parameter>callback</parameter>) to handle
errors in a script.
</para>
<simpara>
Sets a user function (<parameter>callback</parameter>) to handle errors in
a script.
The handler that was active until then is saved on an internal stack of
error handlers, from which <function>restore_error_handler</function> pops
it back.
</simpara>
<para>
This function can be used to define custom error handlers during runtime,
for example in applications which need to do file/data cleanup when a critical
Expand Down Expand Up @@ -62,10 +65,13 @@
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
If &null; is passed, the handler is reset to its default state.
<simpara>
If &null; is passed, no user-defined handler is left active and errors
fall back to the built-in error handler.
The handler that was active until then is still saved on the stack and
can be brought back with <function>restore_error_handler</function>.
Otherwise, the handler is a callback with the following signature:
</para>
</simpara>
<para>
<methodsynopsis>
<type>bool</type><methodname><replaceable>handler</replaceable></methodname>
Expand Down Expand Up @@ -329,24 +335,83 @@ vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Calling the previous handler from the new one</title>
<simpara>
The return value of <function>set_error_handler</function> is the handler
that was active until then. Calling it from the new handler keeps the
existing behaviour while adding to it. This only works if that handler is
a user defined function; &null; is returned when the built-in one was
active.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
function logging_handler(int $errno, string $errstr): bool
{
echo "logged: $errstr\n";
return true;
}

set_error_handler('logging_handler');

$previous = set_error_handler(function (int $errno, string $errstr) use (&$previous): bool {
echo "counted: $errstr\n";
return $previous !== null ? $previous($errno, $errstr) : false;
});

trigger_error("something happened", E_USER_WARNING);

restore_error_handler();
trigger_error("only logged now", E_USER_WARNING);

restore_error_handler();
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
counted: something happened
logged: something happened
logged: only logged now
]]>
</screen>
</example>
</para>
</refsect1>

<refsect1 role="notes">
&reftitle.notes;
<caution>
<simpara>
Do not revert to the previous handler by passing the return value of
<function>set_error_handler</function> back to it.
Doing so pushes a further entry onto the stack instead of removing one,
so the stack grows without bound in loops and long-running processes, and
<parameter>error_levels</parameter> is reset to <constant>E_ALL</constant>,
silently widening the range of errors the restored handler receives.
<function>restore_error_handler</function> is the intended way to revert
to the previous handler.
</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">error level constants</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">error level constants</link></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Expand Down