PHP set_exception_handler() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Error

Definition

In PHP, set_exception_handler() registers a function that runs when an exception is thrown and nothing catches it.

Normally an uncaught exception stops the script with a long fatal error message. With set_exception_handler() you decide what happens instead, such as logging the problem and showing a friendly message. After your handler runs, the script ends, so it is a last safety net and not a replacement for try and catch.

Syntax

Call set_exception_handler() with the values you need. Start with this line.

PHP
set_exception_handler('myExceptionHandler');
CallWhat it does
set_exception_handler('myExceptionHandler')Uses your function as the handler for uncaught exceptions.
set_exception_handler([ErrorPage::class, 'handle'])Uses a static class method as the handler.
set_exception_handler(null)Goes back to PHP's default handling.

The handler receives the exception object. It is only called for exceptions that are not caught by a try and catch block. Once the handler finishes, PHP stops running the script.

Library declarations
PHP
set_exception_handler(?callable $callback): ?callable

Parameters

ParameterDescription
callbackRequired. A function, method or anonymous function that receives the uncaught exception, or null to restore the default behavior. The parameter type is usually Throwable.

Return Value

Return ValueDescription
callableThe previously set exception handler.
nullReturned when there was no previous handler.

PHP Examples

Example 1 — A Last Safety Net

The handler prints a friendly message, and the line after the throw never runs.

PHP
<?php
set_exception_handler(function (Throwable $e): void {
    echo "Unhandled: ", $e->getMessage(), PHP_EOL;
});

echo "Before", PHP_EOL;

throw new RuntimeException("Database is down");

echo "This line never runs", PHP_EOL;

How It Works

  1. set_exception_handler() registers an anonymous function that receives any uncaught exception.
  2. The script prints Before and then throws a RuntimeException that nothing catches.
  3. PHP passes the exception to our function, which prints its message.
  4. The script ends afterwards, so the last echo is never reached.

Example 2 — Using a Class Method as the Handler

You can pass a static method as an array that holds the class name and the method name.

PHP
<?php
class ErrorPage {
    public static function handle(Throwable $e): void {
        echo get_class($e), ": ", $e->getMessage(), PHP_EOL;
    }
}

set_exception_handler([ErrorPage::class, 'handle']);

throw new InvalidArgumentException("Not allowed");

How It Works

  1. ErrorPage::handle() is a static method, so it can be called without creating an object.
  2. [ErrorPage::class, 'handle'] is a callable made from the class name and the method name.
  3. The thrown InvalidArgumentException is not caught anywhere, so PHP calls that method.
  4. get_class() gives the exception type, which we print together with its message.

Example 3 — try and catch Wins, and the Return Value

Caught exceptions never reach the handler. Setting a second handler returns the first one.

PHP
<?php
set_exception_handler(function (Throwable $e): void {
    echo "Global handler: ", $e->getMessage(), PHP_EOL;
});

try {
    throw new Exception("Handled locally");
} catch (Exception $e) {
    echo "Caught: ", $e->getMessage(), PHP_EOL;
}

$previous = set_exception_handler(function (Throwable $e): void {
    echo "New handler: ", $e->getMessage(), PHP_EOL;
});

echo "Previous handler type: ", gettype($previous), PHP_EOL;

throw new LogicException("Final");

How It Works

  1. The first exception is caught by try and catch, so the global handler is never involved.
  2. set_exception_handler() returns the previous handler, which was an anonymous function.
  3. An anonymous function is an object, so gettype() reports object.
  4. The last exception is not caught, so the new handler prints New handler: Final.

Frequently Asked Questions

It sets a function that PHP calls when an exception is thrown and is not caught by any try and catch block.
No. After your handler finishes, PHP ends the script. The code after the throw statement is never executed.
No. Use try and catch for problems you can fix or work around. The exception handler is only a final safety net for exceptions that nobody caught.
A single parameter, usually typed as Throwable so it accepts both exceptions and errors. For example: function (Throwable $e) { ... }.
Call restore_exception_handler() to go back to the previous handler, or call set_exception_handler(null) to use PHP's default behavior.

Next: trigger_error()

trigger_error() creates your own error message at a level you choose, as if PHP itself had.

trigger_error() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful