If a snippet, or sometimes a plugin, contains a fatal PHP error, you may end up looking at the MODX white screen of death. It’s usually a completely blank screen, though if you do a “View Source”, you may see the number one at the upper left of the screen — not much help.
In this article, we’ll look at a method that will sometimes tell you what went wrong.
Plugins make this process challenging because they seldom display errors on the screen. They may place an error in the MODX Error Log that you might not see until much later, by which time there may be many copies of the error message.
The White Screen of Death
Seeing this in MODX is pretty frustrating. It happens because the PHP
error_reporting level and the
display_errors settings are set to hide PHP errors. This is what you want on a production site. The error messages look bad and can give hackers valuable information. When a problem occurs, though, you need to change things temporarily to see what’s happening.
Go to System (Gear Icon) -> System Settings in the MODX Manager, put
debug in the search box at the upper right, and press enter.
You may see several settings (Discuss, for example, has a couple of debug settings). The one you want has the key
debug. This is the MODX debug setting. Make a note of the value so you can change it back later.
Double-click on the “value” field or right-click on it an select “Update Setting.” Change the value to -1, that should show all PHP errors. Click outside the debug setting and wait for the little red triangle to disappear. Then, clear the MODX cache.
When you visit the page again, you should see a PHP error message that tells you the name of the offending file and the line number of the error, though the line number may be off by a few lines. If the error message shows a file under the core/cache directory, it should end in the word plugin or snippet followed by a number. That number is the ID of the snippet or plugin causing the error.
Don’t forget to change the
debug setting back to its original value after you’ve found the problem.
Sometimes, the error message won’t be very helpful because it will point to the MODX
index.php file or a controller file. When a file uses
include to make use of another PHP file, an error in the included file will show up as an error in the including file.
If you’re working in a localhost install of MODX (e.g., under XAMPP), or you have control of the server, you can get a little more information about the error by enabling XDebug.
phpInfo() to find the location of the
php.ini file that PHP is using (there may be several). In the current version of XAMPP, it’s
php.ini file in a text or code editor. Look for the
[XDebug] section. Uncomment these two lines by removing the semicolon at the beginning:
zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
The first line may look different on your platform, but you should be able to find the XDebug extension.
Now, when a PHP fatal error occurs, you may (or may not) see a stack trace showing the series of actions that preceded the error.