Home/ Manual/ errorfunc / functions/ set_exception_handler

set_exception_handler

PHP function Edit on GitHub ✎

(PHP 5, PHP 7, PHP 8)

Sets a user-defined exception handler function

Description

set_exception_handler(callable|null $callback): callable|null

Sets the default exception handler if an exception is not caught within a try/catch block. Execution will stop after the callback is called.

Note

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, set_exception_handler() therefore reports no previously defined handler.

As of PHP 8.3.5 the engine also pushes the handler it is about to invoke onto the handler stack, so restore_exception_handler() called from within a handler re-installs the handler that is currently running rather than the one that was active before it.

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 set_exception_handler() or restore_exception_handler(), this automatic restoration is skipped and the active handler is whatever the handler itself left in place.

Modifying the exception handler from within itself is therefore discouraged.

Parameters

callback

The function to be called when an uncaught exception occurs. This handler function needs to accept one parameter, which will be the Throwable object that was thrown. Both Error and Exception implement the Throwable interface. This is the handler signature:

handler(Throwable $ex): void

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

Return Values

Returns the previously defined exception handler, or null on error. If no previous handler was defined, null is also returned.

Changelog

Version	Description
8.3.5	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.
8.3.0	The active exception handler is now unset while it runs, so `set_exception_handler()` called from within a handler reports no previously defined handler.

Examples

set_exception_handler() example

php

<?php
function exception_handler(Throwable $exception) {
  echo "Uncaught exception: " , $exception->getMessage(), "\n";
}

set_exception_handler('exception_handler');

throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>