How to Catch a PHP Fatal (E_ERROR) Error

In PHP, fatal errors (such as E_ERROR) can cause a script to terminate immediately, making it challenging to capture and handle these errors. While PHP’s set_error_handler() function allows catching many types of errors, it doesn’t work for fatal errors. In this post, we’ll explore different ways to handle fatal errors effectively, especially in older versions of PHP, and how PHP 7+ offers a more structured approach to error handling.

Problem with Catching Fatal Errors

Fatal errors in PHP, like calling a non-existent function or running out of memory, cannot be caught by set_error_handler() because these errors cause the script to terminate before reaching the handler. For example, this code will not catch a fatal error:

function errorHandler($errno, $errstr) {
    echo "Error: [$errno] $errstr";
}

set_error_handler('errorHandler');

// This will not be caught
undefinedFunctionCall();

So, how can we handle fatal errors gracefully?

Solution for PHP 5.2+ Using register_shutdown_function()

In PHP 5.2 and above, you can use register_shutdown_function() to register a function that will be executed when the script shuts down. This function can detect if a fatal error has occurred and handle it accordingly. Here’s an example:

register_shutdown_function('handleFatalError');

function handleFatalError() {
    $error = error_get_last();
    
    if ($error && $error['type'] === E_ERROR) {
        // Handle the fatal error
        echo "A fatal error occurred: {$error['message']} in {$error['file']} on line {$error['line']}";
    }
}

How It Works:

• register_shutdown_function() registers a callback function that is executed when the script terminates, regardless of how the termination occurred (normal or due to a fatal error).
• error_get_last() retrieves the last error that occurred, including fatal errors.
• By checking the type of the error (E_ERROR in this case), you can determine if a fatal error occurred and handle it appropriately.

This method allows you to log the error, send a notification, or perform any other cleanup tasks before the script ends.

Example with Email Notification

You might want to send an email notification whenever a fatal error occurs. Here’s how you can modify the handleFatalError function to send an email:

register_shutdown_function('handleFatalError');

function handleFatalError() {
    $error = error_get_last();
    
    if ($error && $error['type'] === E_ERROR) {
        $message = "Fatal error: {$error['message']} in {$error['file']} on line {$error['line']}";
        
        // Send email notification
        mail('admin@example.com', 'Fatal Error in Script', $message);
        
        echo "An error occurred. The administrator has been notified.";
    }
}

In this example:

• When a fatal error occurs, an email is sent to the administrator with details about the error.
• You can replace mail() with any logging mechanism or alert system that suits your needs.

Limitations of register_shutdown_function()

• Not for Recovering: While this method helps log or handle the error, it doesn’t allow you to recover from a fatal error. Once a fatal error occurs, PHP still terminates the script.
• Memory Exhaustion: If the fatal error is due to memory exhaustion, the shutdown function might not have enough memory to run properly. You should handle memory allocation carefully when using this approach.

Error Handling in PHP 7+ with Error and Throwable

Starting from PHP 7, PHP introduced a more structured way to handle fatal errors. Fatal errors now throw instances of the Error class, which extends the Throwable interface. This allows you to catch fatal errors just like exceptions using try-catch blocks.

Example of Catching Fatal Errors in PHP 7+

try {
    // This will throw an Error object
    undefinedFunctionCall();
} catch (Error $e) {
    echo "Caught fatal error: " . $e->getMessage();
}

Using Throwable to Catch All Errors and Exceptions

In PHP 7 and above, you can use the Throwable interface to catch both Error and Exception objects in a single block:

try {
    // Code that may cause an error or exception
    undefinedFunctionCall();
} catch (Throwable $e) {
    echo "Caught throwable: " . $e->getMessage();
}

This provides a more elegant way to handle both fatal errors and exceptions, making your error handling more consistent and robust.

Summary of Approaches

PHP 5.2 and Higher:

• Use register_shutdown_function() to capture and handle fatal errors.
• Use error_get_last() inside the shutdown function to retrieve the last error, check if it’s fatal (E_ERROR), and handle it.
• This method is useful for logging and notifications but does not allow recovery from fatal errors.

PHP 7 and Higher:

• PHP 7 introduced the Error class and the Throwable interface, allowing you to catch fatal errors using try-catch blocks.
• This provides more flexibility in handling errors and can be used to catch all types of errors and exceptions in a single block.

Catching fatal errors in PHP requires different approaches depending on the version of PHP you’re using. In older versions, register_shutdown_function() is the best way to detect and log fatal errors, while in PHP 7 and later, the introduction of the Error class and the Throwable interface allows more granular error handling.