PHP set_exception_handler() Function: Usage and Examples

Registers a callback PHP invokes for uncaught Throwable instances.

The examples focus on the operation itself, including the important distinction: restore_exception_handler restores the previously active exception handler.

What It Does

Use the examples below to observe the behavior on a small dataset before extending it to application code.

Syntax and Return Value

set_exception_handler(?callable $callback)

The displayed signature describes the API or identifies any correction or optional dependency. When a parameter is optional, supply it only when the task requires it.

Parameters

• callback: required.

Example 1: Basic Use

A global handler is a last-resort mechanism for uncaught Throwable instances; register it early and avoid exposing exception messages to clients.

<?php
$previous = set_exception_handler(static function (Throwable $e): void {
    error_log("Unhandled exception: " . get_class($e));
    http_response_code(500);
});
echo $previous === null ? "first handler" : "handler replaced";
restore_exception_handler();

Output from a successful local PHP 8.4 run:

first handler

Example 2: Checking Behavior

A global handler is a last-resort mechanism for uncaught Throwable instances; register it early and avoid exposing exception messages to clients. This tests installing and restoring the global handler without leaking exception details.

<?php
$previous = set_exception_handler(static function (Throwable $e): void {
    error_log("Unhandled exception: " . get_class($e));
    http_response_code(500);
});
echo $previous === null ? "first handler" : "handler replaced";
$replacement = set_exception_handler(static fn(Throwable $e) => error_log("Second handler"));
restore_exception_handler();
restore_exception_handler();

Output from a successful local PHP 8.4 run:

first handler

Example 3: Practical Example

A global handler is a last-resort mechanism for uncaught Throwable instances; register it early and avoid exposing exception messages to clients. This tests installing and restoring the global handler without leaking exception details.

<?php
$previous = set_exception_handler(static function (Throwable $e): void {
    error_log("Unhandled exception: " . get_class($e));
    http_response_code(500);
});
echo is_callable($previous) ? "handler chained" : "initial handler";
restore_exception_handler();

Output from a successful local PHP 8.4 run:

initial handler

Important Behavior and Edge Cases

The handler does not replace local try/catch, and its own uncaught exception must be avoided.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Registers a callback PHP invokes for uncaught Throwable instances.
• The handler does not replace local try/catch, and its own uncaught exception must be avoided.
• restore_exception_handler restores the previously active exception handler.

Use set_exception_handler when its documented behavior matches the problem. Test the relevant edge cases in your own runtime before deploying it.