PHP restore_exception_handler() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Error

Definition

In PHP, restore_exception_handler() goes back to the exception handler that was active before the most recent call to set_exception_handler().

Exception handlers are kept in a stack, just like error handlers. Each set_exception_handler() puts a handler on top, and restore_exception_handler() takes it off. If there was no earlier handler, uncaught exceptions are handled in PHP's default way again.

Syntax

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

PHP
restore_exception_handler();
CallWhat it does
restore_exception_handler()Removes the current exception handler and brings back the previous one.
set_exception_handler($fn); /* work */ restore_exception_handler();Uses a handler for a short piece of code and then removes it.
var_dump(restore_exception_handler())Prints bool(true), because the function always returns true.

It always returns true, even when no handler was set. It does not catch exceptions. It only changes which handler would run for an uncaught exception.

Library declarations
PHP
restore_exception_handler(): true

Parameters

ParameterDescription
—This function takes no parameters.

Return Value

Return ValueDescription
trueAlways returns true.

PHP Examples

Example 1 — Going Back to the Previous Handler

Two handlers are set. After restoring, the first one handles the uncaught exception.

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

set_exception_handler(function (Throwable $e): void {
    echo "Handler B: ", $e->getMessage(), PHP_EOL;
});

restore_exception_handler();

echo "Throwing...", PHP_EOL;
throw new Exception("Oops");

How It Works

  1. Handler A is registered first, and Handler B is registered on top of it.
  2. restore_exception_handler() removes Handler B, so Handler A is active again.
  3. The script prints Throwing. .. and then throws an exception that nobody catches.
  4. PHP calls the active exception handler, Handler A, and the script ends.

Example 2 — What set_exception_handler() Returns After a Restore

set_exception_handler() returns the previous handler. After a restore, that previous handler is the one that was brought back.

PHP
<?php
function firstHandler(Throwable $e): void {}
function secondHandler(Throwable $e): void {}
function thirdHandler(Throwable $e): void {}

set_exception_handler('firstHandler');
set_exception_handler('secondHandler');

restore_exception_handler();

$previous = set_exception_handler('thirdHandler');
echo "Previous handler: ", $previous, PHP_EOL;

How It Works

  1. firstHandler and secondHandler are registered, and secondHandler is on top.
  2. restore_exception_handler() removes secondHandler.
  3. set_exception_handler('thirdHandler') returns whatever handler was active just before it.
  4. That handler is firstHandler, which proves the restore worked.

Example 3 — Return Value and the Default Handler

The function returns true. When no handler is left, the next set_exception_handler() returns null.

PHP
<?php
function myHandler(Throwable $e): void {}

set_exception_handler('myHandler');

var_dump(restore_exception_handler());
var_dump(set_exception_handler('myHandler'));

How It Works

  1. myHandler is registered as the only exception handler.
  2. restore_exception_handler() removes it and returns true.
  3. No handler is active now, so PHP's default behavior is back.
  4. The next set_exception_handler() returns NULL, because there was no previous handler.

Frequently Asked Questions

It removes the current exception handler and brings back the one that was active before it. If there was none, PHP's default behavior for uncaught exceptions is used.
It always returns true.
No. It only changes which function is called for uncaught exceptions. To catch an exception yourself, use try and catch.
Nothing bad happens. The function still returns true and PHP keeps using its default handling.
restore_exception_handler() works on the stack of exception handlers, and restore_error_handler() works on the stack of error handlers. They do not affect each other.

Next: set_error_handler()

set_error_handler() lets you choose your own function to handle errors such as warnings an.

set_error_handler() 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