Documentation Index

The Dreaded White Screen and Other Errors

Our error handling is evolving. It has changed several times already and may change again.

Errors Disabled

Sometimes during development a PHP program will err and leave a white screen. This could be due to an error reporting setting of 0 or by the PHP directive display_errors setting of 0.

THIS uses an error handler and it can be controlled in a number of ways in how to display errors. (A PHP error handler will not be able to catch errors such as fatal and parse errors.)

The file ERROR.PHP has the error handling code. We do not use a configuration setting to set the error level as we need it set as early as possible. Right at the top of ERROR.PHP — which is included early by INDEX.PHP — are the lines:

    //ini_set('display_errors',1);
    
error_reporting(0);                // when upgrading use E_ERROR|E_PARSE

This prevents all error messages from being displayed. They are still caught by the error handler — with the exception of fatal and parse errors. This means that a white screen is possible.

But as administrator, you need to know what the error is. And it may be that such errors are not in the log file (or you may not have access to the error log file).

Errors Enabled

When we are upgrading the code and get a white screen, as we frequently do, we simply manually change the error level to E_ERROR|E_PARSE. If your host has display_errors turned off you can then uncomment the ini_set() call.

This will display the error. (We are thinking about a way to allow this only if logged in as Admin — the admin cookie is set — so that other users will not see the error message.)

Selective Error Display

There are a number of ways to show PHP warnings and notices when the code is stable but something went wrong. These are the CONFIG.INI settings, initially set to 0:

        shownotices
        showerrors
        shownotfounds
        failnotemplate

The shownotices of 1 displays E_NOTICE messages, like for undefined variables. Undefined variables are actually common and harmless in some of the templates.

The showerrors setting can turn on the display of web template parse errors. Web templates are are loaded simply as data and are parsed when displayed. If a template has a parse error it will not be displayed.

The shownotfounds setting can enable messages for missing web templates.

The failnotemplate setting will issue a message and exit if there is a missing or if there is a parse error in a PHP format data file (such as TRANSLATE.INI or TEMPLATES.PHP). Sometimes minor errors will not be so bad and this being off will allow the site to be displayed while being edited.

Debug Output

When debugging is enabled (the debug CONFIG.INI setting, see file DEBUGGING) all PHP errors are put into the debug message list. Undefined variable notices in web templates are harmless and may be common. There is a setting, debugnotices, to disable these.

Editing The Site Live

One of the reasons for suppressing template errors is when Admin is being used to adjust the site live. If a syntax error made it into a template, that template will be blank — and the Admin this will see this right away (and perhaps debug will be set). The Admin will then be able to look for and fix the error.

If Admin let a syntax error get into TRANSLATE.INI, the post markup language, the site will still run, simply without the translations occurring. Again, Admin will then be able to look for and fix the error.

The code is still being adjusted toward having a very robust site. The Admin editor will eventually "syntax check" all configuration data to prevent errors from being saved. In addition, an elaborate HTML FORM based editor will replace the current editor which is simply a TEXTAREA.

Notes

1. See the top of INDEX.PHP for how to turn on "maintenance mode".
2. In the previous releases there were a great many of these due to our excessive use of the PHP error operator, @, on accessing possibly undefined variables — we have fixed all of these.
3. As mentioned in the message above we will have a template editor that prevents errors from being saved.