<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Sets a user-defined exception handler function</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.set-error-handler.html">set_error_handler</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.trigger-error.html">trigger_error</a></div>
<div class="up"><a href="ref.errorfunc.html">Error Handling Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.set-exception-handler" class="refentry">
<div class="refnamediv">
<h1 class="refname">set_exception_handler</h1>
<p class="verinfo">(PHP 5, PHP 7)</p><p class="refpurpose"><span class="refname">set_exception_handler</span> — <span class="dc-title">
Sets a user-defined exception handler function
</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.set-exception-handler-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <span class="methodname"><strong>set_exception_handler</strong></span>
( <span class="methodparam"><span class="type"><a href="language.types.callable.html" class="type callable">callable</a></span> <code class="parameter">$exception_handler</code></span>
)</div>
<p class="para rdfs-comment">
Sets the default exception handler if an exception is not caught within a
try/catch block. Execution will stop after the
<code class="parameter">exception_handler</code> is called.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.set-exception-handler-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<code class="parameter">exception_handler</code></dt>
<dd>
<p class="para">
Name of the function to be called when an uncaught exception occurs.
This handler function
needs to accept one parameter, which will be the exception object that
was thrown. This is the handler signature before PHP 7:
</p>
<p class="para">
<div class="methodsynopsis dc-description">
<span class="type"><span class="type void">void</span></span> <span class="methodname"><span class="replaceable">handler</span></span>
( <span class="methodparam"><span class="type"><a href="class.exception.html" class="type Exception">Exception</a></span> <code class="parameter">$ex</code></span>
)</div>
</p>
<p class="para">
Since PHP 7, most errors are reported by throwing <a href="class.error.html" class="classname">Error</a>
exceptions, which will be caught by the handler as well. Both <a href="class.error.html" class="classname">Error</a>
and <a href="class.exception.html" class="classname">Exception</a> implements the <a href="class.throwable.html" class="classname">Throwable</a> interface.
This is the handler signature since PHP 7:
</p>
<p class="para">
<div class="methodsynopsis dc-description">
<span class="type"><span class="type void">void</span></span> <span class="methodname"><span class="replaceable">handler</span></span>
( <span class="methodparam"><span class="type"><a href="class.throwable.html" class="type Throwable">Throwable</a></span> <code class="parameter">$ex</code></span>
)</div>
</p>
<p class="para">
<strong><code>NULL</code></strong> may be passed instead, to reset this handler to its default state.
</p>
<div class="caution"><strong class="caution">Caution</strong>
<p class="para">
Note that providing an explicit <a href="class.exception.html" class="classname">Exception</a> type
hint for the <code class="parameter">ex</code> parameter in your callback will
cause issues with the changed exception hierarchy in PHP 7.
</p>
</div>
</dd>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.set-exception-handler-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the name of the previously defined exception handler, or <strong><code>NULL</code></strong> on error. If
no previous handler was defined, <strong><code>NULL</code></strong> is also returned.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.set-exception-handler-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>7.0.0</td>
<td>
The type of parameter passed into <code class="parameter">exception_handler</code> changed
from <a href="class.exception.html" class="classname">Exception</a> to <a href="class.throwable.html" class="classname">Throwable</a>
</td>
</tr>
<tr>
<td>5.5.0</td>
<td>
Previously, if <strong><code>NULL</code></strong> was passed then this function returned <strong><code>TRUE</code></strong>.
It returns the previous handler since PHP 5.5.0.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.set-exception-handler-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-498">
<p><strong>Example #1 <span class="function"><strong>set_exception_handler()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">exception_handler</span><span style="color: #007700">(</span><span style="color: #0000BB">$exception</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"Uncaught exception: " </span><span style="color: #007700">, </span><span style="color: #0000BB">$exception</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">(), </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">set_exception_handler</span><span style="color: #007700">(</span><span style="color: #DD0000">'exception_handler'</span><span style="color: #007700">);<br /><br />throw new </span><span style="color: #0000BB">Exception</span><span style="color: #007700">(</span><span style="color: #DD0000">'Uncaught Exception'</span><span style="color: #007700">);<br />echo </span><span style="color: #DD0000">"Not Executed\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.set-exception-handler-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><span class="function"><a href="function.restore-exception-handler.html" class="function" rel="rdfs-seeAlso">restore_exception_handler()</a> - Restores the previously defined exception handler function</span></li>
<li class="member"><span class="function"><a href="function.restore-error-handler.html" class="function" rel="rdfs-seeAlso">restore_error_handler()</a> - Restores the previous error handler function</span></li>
<li class="member"><span class="function"><a href="function.error-reporting.html" class="function" rel="rdfs-seeAlso">error_reporting()</a> - Sets which PHP errors are reported</span></li>
<li class="member">information about the <a href="language.pseudo-types.html#language.types.callback" class="link">callback</a> type</li>
<li class="member"><a href="language.exceptions.html" class="link">PHP 5 Exceptions</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.set-error-handler.html">set_error_handler</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.trigger-error.html">trigger_error</a></div>
<div class="up"><a href="ref.errorfunc.html">Error Handling Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
