Creating a Custom Fatal PHP Error Handler in WordPress

In this blog post, we will explain the provided code that defines a custom PHP error handler in a WordPress environment. This error handler is designed to create a dedicated PHP error page if it doesn’t already exist. Let’s break down the code step by step:

Purpose

The purpose of this code is to create a custom PHP error handler for a WordPress website. It ensures that if an error occurs within the WordPress environment and a specific error file (php-error.php) doesn’t already exist, this code will generate the error file. The error file contains code to handle and display error messages in a structured and user-friendly format, helping administrators and developers to diagnose and address issues with the website.

By creating and using the php-error.php file, the code intercepts any PHP errors that occur within the WordPress environment. Instead of displaying the standard, often cryptic PHP error message to users, the custom error handler will present a more user-friendly and informative error message with details such as the error message itself, the file where it occurred, the line number, the current URL, the referrer, and the date and time of the error. This user-friendly presentation helps both administrators and developers quickly understand and address errors, improving the overall user experience and simplifying troubleshooting in a WordPress website.

Implementation

Before implementing the provided code, ensure that the following prerequisite is met:

WP DEBUG Set to True: Make sure that WordPress debugging (WP_DEBUG) is set to true in your WordPress configuration (wp-config.php) to enable detailed error logging and reporting. This setting is essential for effective error handling and debugging when using the custom error handler code. You can set it as follows:

// wp-config.php

define( 'WP_DEBUG', true );

or

define( 'DEBUG_IPS', array(
        '202.7.218.202', // Replace with your development team's IP addresses
)) ; 

Code Explanation

This code first defines a file path for the php-error.php file within the WordPress installation directory. It then checks if this file already exists; if not, it proceeds to create it. The content of the error file includes PHP code that handles errors by collecting information about the error, such as the error message, file, line number, and current URL, and then displays this information in a formatted error message with a red background.

Important Considerations

It’s crucial to be aware that the code provided will display error messages within a red box for debugging purposes. However, it should be removed or disabled in a live environment to maintain a professional appearance and security. Alternatively, you can enable IP address-based debugging by adding a define statement to your WordPress configuration (wp-config.php).

Code

Add this code to your plugin or theme functions.php file.

Remove the code and the PHP error file once utilised.

// Define the file path for php-error.php
$file_path = ABSPATH . 'wp-content/php-error.php';

// Content for php-error.php
$content = '<?php
if ( ! defined( "ABSPATH" ) ) {
    exit;
}

// Check if WP_DEBUG is set to true or IP address is in the allowed list
if ( ( defined( "WP_DEBUG" ) && WP_DEBUG ) || ( defined( "DEBUG_IPS" ) && in_array( $_SERVER["REMOTE_ADDR"], DEBUG_IPS ) ) ) {
    $protocol = isset( $_SERVER["HTTPS"] ) && $_SERVER["HTTPS"] === "on" ? "https" : "http";
    $host = $_SERVER["HTTP_HOST"];
    $request_uri = $_SERVER["REQUEST_URI"];

    $error_message = sanitize_text_field( nl2br( $error["message"] ) );
    $error_file = sanitize_text_field( $error["file"] );
    $error_line = sanitize_text_field( $error["line"] );
    $current_url = esc_url( "$protocol://$host$request_uri" );
    $current_datetime = date( "d-m-Y H:i:s" );

    // Modify the content to display an error message with a red background
    echo \'<div style="background-color: red; color: white; padding: 10px;">\';
    echo \'<p>\';
    echo \'Oops, we\\\'re experiencing technical difficulties. We\\\'re onto it. Please check again soon.</p>\';
    echo \'<p>\';
    echo \'FATAL ERROR on \' . $current_url . \'<br><br>\';
    echo \'File: \' . $error_file . \'<br><br>\';
    echo \'Message: \' . $error_message . \'<br><br>\';
    echo \'Line: \' . $error_line . \'<br><br>\';
    echo \'URL: \' . $current_url . \'<br><br>\';
    echo \'Date: \' . $current_datetime;
    echo \'</p>\';
    echo \'</div>\';
}
?>';

// Create the file and write the content
file_put_contents( $file_path, $content );

#fatal error #php error