<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.set-exception-handler" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>set_exception_handler</refname>

<refpurpose>

Sets a user-defined exception handler function

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>callable</type><type>null</type></type><methodname>set_exception_handler</methodname>

<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>

</methodsynopsis>

<para>

Sets the default exception handler if an exception is not caught within a

try/catch block. Execution will stop after the

<parameter>callback</parameter> is called.

</para>

<note>

<simpara>

While an exception handler is running, no exception handler is active: as of

PHP 8.3.0 the engine unsets it before invoking it, so that an exception

thrown by the handler is not passed back to it. Called from within a handler,

<function>set_exception_handler</function> therefore reports no previously

defined handler.

</simpara>

<simpara>

As of PHP 8.3.5 the engine also pushes the handler it is about to invoke onto

the handler stack, so <function>restore_exception_handler</function> called

from within a handler re-installs the handler that is currently running

rather than the one that was active before it.

</simpara>

<simpara>

The running handler is re-installed automatically when it returns, but only

if no exception handler is active at that point. As soon as the handler calls

<function>set_exception_handler</function> or

<function>restore_exception_handler</function>, this automatic restoration is

skipped and the active handler is whatever the handler itself left in place.

</simpara>

<simpara>

Modifying the exception handler from within itself is therefore discouraged.

</simpara>

</note>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<para>

The function to be called when an uncaught exception occurs.

This handler function needs to accept one parameter,

which will be the <classname>Throwable</classname> object that was thrown.

Both <classname>Error</classname> and <classname>Exception</classname>

implement the <classname>Throwable</classname> interface.

This is the handler signature:

</para>

<para>

<methodsynopsis>

<type>void</type><methodname><replaceable>handler</replaceable></methodname>

<methodparam><type>Throwable</type><parameter>ex</parameter></methodparam>

</methodsynopsis>

</para>

<para>

&null; may be passed instead, to reset this handler to its default state.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Returns the previously defined exception handler, or &null; on error. If

no previous handler was defined, &null; is also returned.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.3.5</entry>

<entry>

The exception handler being invoked is now pushed onto the handler stack

and re-installed once it returns, unless the handler modified the stack

itself.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

The active exception handler is now unset while it runs, so

<function>set_exception_handler</function> called from within a handler

reports no previously defined handler.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>set_exception_handler</function> example</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso"><!-- {{{ -->

&reftitle.seealso;

<simplelist>

<member><function>get_exception_handler</function></member>

<member><function>restore_exception_handler</function></member>

<member><function>restore_error_handler</function></member>

<member><function>error_reporting</function></member>

<member><link linkend="language.exceptions">Exceptions</link></member>

</simplelist>

</refsect1><!-- }}} -->

</refentry>