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.
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.