<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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>callable</type><methodname>set_exception_handler</methodname>
   <methodparam><type>callable</type><parameter>exception_handler</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>exception_handler</parameter> is called.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>exception_handler</parameter></term>
     <listitem>
      <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:
      </para>
      <para>
       <methodsynopsis>
        <type>void</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>Exception</type><parameter>ex</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Since PHP 7, most errors are reported by throwing <classname>Error</classname>
       exceptions, which will be caught by the handler as well. Both <classname>Error</classname>
       and <classname>Exception</classname> implements the <classname>Throwable</classname> interface.
       This is the handler signature since PHP 7:
      </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>
      <caution>
       <para>
        Note that providing an explicit <classname>Exception</classname> type
        hint for the <parameter>ex</parameter> parameter in your callback will
        cause issues with the changed exception hierarchy in PHP 7.
       </para>
      </caution>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the name of 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>7.0.0</entry>
       <entry>
        The type of parameter passed into <parameter>exception_handler</parameter> changed
        from <classname>Exception</classname> to <classname>Throwable</classname>
       </entry>
      </row>
      <row>
       <entry>5.5.0</entry>
       <entry>
        Previously, if &null; was passed then this function returned &true;.
        It returns the previous handler since PHP 5.5.0.
       </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">
<![CDATA[
<?php
function exception_handler($exception) {
  echo "Uncaught exception: " , $exception->getMessage(), "\n";
}

set_exception_handler('exception_handler');

throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso"><!-- {{{ -->
  &reftitle.seealso;
  <para>
   <simplelist>
    <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">PHP 5 Exceptions</link></member>
   </simplelist>
  </para>
 </refsect1><!-- }}} -->

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->