Custom fatal error message for eZ Publish (legacy)

Until some time ago, it was necessary to hack the eZ Publish legacy kernel in order to customize its generic error message, "Fatal error: The web server did not finish its request". This error occurs on all eZ Publish installations whenever there is an HTTP 500 status server error. It is a very common error; some examples of how it's triggered include: trying to access the value of a non-existent object attribute; the use of a non-existent PHP class or function; and too much memory usage.

Now, since this pull request from Mugo has been merged to the eZ Publish kernel, we have made it possible to customize the error page without hacking the kernel. In this post I will show you the new standard way to do this with a simple INI setting and your own PHP function.

Here's the default HTTP 500 error message:

In order to use your own function, you need to override the global error.ini file (settings/override/error.ini.append.php), and define the following setting:

[ErrorSettings-kernel]
FatalErrorHandler=CustomFatalErrorHandlerClass::FatalErrorHandlerFunction

CustomFatalErrorHandlerClass can be any class, and FatalErrorHandlerFunction must be a public static function of the specified class.

class CustomFatalErrorHandlerClass
{
    public static function FatalErrorHandlerFunction()
    {
        header("HTTP/1.1 500 Internal Server Error");
        echo '<strong>Sorry!</strong> Something has gone wrong. We have logged the error but feel free to <a href="/contact">contact us</a>';
        eZDisplayResult(null);
    }
}

That's all you need to customize the error page!

It is also possible to use an eZ Publish template.

class CustomFatalErrorHandlerClass
{
    public static function FatalErrorHandlerFunction()
    {
        header("HTTP/1.1 500 Internal Server Error");
        $tpl = eZTemplate::factory();
        echo $tpl->fetch( 'design:error500.tpl' );
        eZExecution::cleanExit();
    }
}

This way, you have full control over the style of the error page. You can add images and use your own stylesheet, just like any other page on your site.