Digging into WordPress » errors

Create a Custom Database Error Page in WordPress

Jeff Starr — Mon, 30 Nov 2009 19:12:46 +0000

As a dynamic blogging system, WordPress consists of PHP files (the WP core) that interact with a MySQL database to generate the web pages for your website. When everything is working properly, this dynamic interaction keeps WordPress humming along like a champ, but when your database crashes, WordPress can’t operate and will deliver the following message to your visitors:

The question is, could this information help an attacker who has targeted your site? This type of specific information should be going to you, the site administrator — not announced to the entire world. Besides, that message really isn’t helping anyone. To the average visitor, it just means the site is borked and that it’s time to move on to someplace else. And to you, the site Admin, the default error message doesn’t mean anything unless you’re lucky enough to be sitting there looking at your site when it happens. I think it’s safe to say that the default database error message:

is ugly
is useless to visitors
is useless to site admins
reveals sensitive information

Fortunately, we can improve on all these areas by creating and implementing our own custom database error page. In this article, you’ll learn how to setup your own error page and add some server-side functionality that will improve your ability to respond to database problems as soon as they happen.

How it works

Basically, it all happens automatically: whenever WordPress is unable to connect to the database, it will check for the presence of your custom error page and then serve it up to your visitors; otherwise, if a custom error page is not present, the default error page is displayed. It’s that simple.

How to set it up

To create your own database error page, simply create your custom page, name it “db-error.php”, and upload it to the wp-content directory like so:

wp-content/db-error.php

That’s pretty much all there is to it. Most of the action happens behind the scenes depending on how you set things up. Because this is an actual PHP file, you can implement just about any non-database functionality, along with whatever markup and CSS you desire.

So, now that we know the dark secrets that make this work, let’s look at an actual example..

An actual example of a custom database error page

Here is the code that I use at Perishable Press:




	
		503 Service Temporarily Unavailable
		
	
	
		Captain, the ship can’t take much more of this!
		Perishable Press is currently experiencing technical issues — Please check back soon!

Simple, yes, but more effective than the default error page at facilitating a rapid response. Again, because this is a regular PHP file, we can do just about anything with it — more functionality, elaborate design, etc. — but before we look at some ideas, let’s browse the basics of this file:

The PHP (before the markup)

Send a 503 server response to let the client know that they should try back later
Send a 503 status response to let the client know that they should try back later
Send a Retry-After header to tell the client when to try again (specified in seconds)
Send an email to the site admin letting them know that “There is a problem with teh database!”

The HTML markup

HTML 5, baby!
Give it a title, might as well call it what it is
Add some CSS to make it all sweet
Throw down some custom markup and tell the user what’s up

From here, you can do just about anything. The PHP stuff is important to let robots and yourself know about the issue, and the markup is important for your human guests. For them, you may integrate your site’s design as much (or as little) as desired. There really is no reason to get too fancy because ideally the page will be displayed for only a brief period. But I suppose if you’re hosted on a crappy server you may want to pimp it out more fully ;)

In any case, here are some more ideas and tips for customizing your own database error page:

Make it more official with your logo and other branding embellishments
Link to some useful resources, perhaps some static stuff not dependent on the database (RSS Feed?)
Don’t disclose the specific issue (i.e., database) — keep it general, like “technical issues” or whatever
If your database is down for awhile, save some bandwidth by keeping this file as small and optimized as possible

It would be so cool if..

As it currently stands, this custom database error page is going to send you an email every single time any WordPress page is requested while the database is down. Especially for highly trafficked sites, this could result in thousands of emails flowing into your inbox. On smaller sites, this isn’t really that big of an issue, but for larger sites it would be cool to get a script that would send only one email for each time the database went down. One way to do this would be to use fwrite to alter a static file with some specific text and then check for it before sending the next email, but this would require all sorts of fiddling that seems extraneous. I’m sure there is a better way of doing it.

Last words

Hopefully this post gives you some ideas of what’s possible with your own custom database error pages. It’s nice that WordPress makes them so easy to set up and customize. Even better, because the db-error.php page is located in the wp-content directory, it is not modified or removed during the upgrade process. So just fix it and forget it. Definitely worthwhile to improve your site’s overall visitor experience.

Rude Things Plugins Can Do

Chris Coyier — Fri, 16 Oct 2009 14:00:11 +0000

I heart plugin authors. Their work is generally amazing, a huge benefit to the community, the reason why WordPress rules so much, and deserving of much worship. That being said, plugins can do some pretty rude things sometimes…

Deactivate Themselves

I had a plugin that I used that liked to deactivate it itself when you upgraded it. I can’t say for absolutely sure why. Perhaps it wasn’t able to save settings after an upgrade and the default was off so when you upgraded it turned off. Perhaps there were new options so the author wanted people to go to the settings page to see all the new stuff. This particular plugin had all kinds of crap in the header of plugin about following him on Twitter and donating, so it was my suspicion that the turning off of the plugin was directed at making people look at all that stuff every time an upgrade was pushed out. He probably saw an uptick in donations when upgrades when out, so there was incentive to keep pushing out minor updates that shut off the plugin.

Break Stuff

Plugin authors are generally smart folks who realize that plugins meant to be used by a wide audience need to be as fool-proof as possible. If the plugin is complicated and requires use of outside files or interaction with other (theoretically default) WordPress files, testing should be done against a variety of installs and in conjunction with other popular plugins to make sure there are no conflicts.

If the plugin tinkers with existing functions, every one of them should be clearly explained so users can understand that use of those functions elsewhere may not behave as expected. Even things as simple as file paths can be problematic. As basic as that sounds, file paths should never be hard-coded.

Have Bad Documentation

To the best of the author’s ability, all plugins should include plain English explanations of why the plugin was created and what goal it hopes to accomplish. Beyond that, instructions for installation and uninstalling should be included. The WordPress plugin directory does a good job of providing “tabs” at the top of plugin pages for including this information. Also important is the FAQ section, which gives plugin authors another opportunity for plain English speak that is free from the sales-y introduction you have to do on the main page.

Insert Crap

Plugin authors know there are some hooks that almost everyone has, like wp_footer(). Hey why not add a force in a line of text down there linking back to the author site? Because that’s rude, that’s why.

Make You Sign up for a Newsletter

There was a plugin I once used fairly regularly that required “activation” that you got via email after signing up for the author’s email. That’s some strong-arm bullshit right there. And do you think this newsletter came only rarely and tastefully with important info? Obviously no, it came all the time, looked like shit, and was loaded with in-your-face proposals. Now there is a plugin that does the same thing without all that. Guess which one I use and support?

Not Update

WordPress changes, users needs change, so plugins need to update. If the plugin is so simple and sound it doesn’t really need constant point releases, its still important to go in to the documentation and indicate it is compatible with the most recent version of WordPress when that changes.

Don’t Have Changelogs

When a plugin does update, there should be at least some basic text explain what was changed and why. I always much appreciate plugin updates, but I’m not going to click that button until I can read from the author what was changed.

3 Ways to Monitor PHP Errors

Jeff Starr — Mon, 27 Jul 2009 05:51:22 +0000

Close monitoring of your site’s PHP errors is crucial to operating a healthy, secure, and well-performing website. When left undetected, PHP errors can reduce performance, waste bandwidth, and leave your site vulnerable to malicious attack. PHP errors usually occur unpredictably and spontaneously, and may be triggered by even the slightest changes to your server configuration, database setup, or WordPress files. Even if your site appears to working properly on the surface, it may in fact be suffering from undetected PHP errors that should be fixed as soon as possible.

Monitoring PHP errors is something that all responsible WordPress administrators should be doing. In this DiW article, we’ll show you three easy ways to monitor PHP errors for WordPress. The first method is exclusive to WordPress, and the second two methods work great for any website.

Method 1: Error Logging via the WordPress configuration file

Perhaps the easiest way to implement PHP error-logging for your WordPress-powered site is to add a few simple lines of code to your wp-config.php file. The WordPress wp-config.php file may be used to specify various PHP initiation settings to modify the functionality of your PHP installation. In this method, we will take advantage of this feature by implementing basic error monitoring for your site. Here’s how to do it:

Step 1: Create a log file

Create an empty file called “php-errors.log”. This file will serve as your site’s PHP error log. Your server will need write access to this file, so make sure to set the appropriate permissions. This file may be placed in any directory, but placing it above the web-accessible root directory of your site is advisable for security reasons. Once this file is created, writable, and in place, take note of its absolute directory path and continue to the final step.

Step 2: Add the magic code

Next, open your site’s wp-config.php file (located in the root WordPress directory) and place the following code immediately above the line that says, “That's all, stop editing! Happy blogging.”:

// log php errors
@ini_set('log_errors','On'); // enable or disable php error logging (use 'On' or 'Off')
@ini_set('display_errors','Off'); // enable or disable public display of errors (use 'On' or 'Off')
@ini_set('error_log','/home/path/logs/php-errors.log'); // path to server-writable log file

Once in place, edit the third line with the absolute directory path to the php-errors.log file created in the first step. Upload to your server and call it done. All PHP errors will now be logged to your php-errors.log file, thereby enabling you to monitor and resolve errors as quickly as possible.

The other two directives in this tasty little snippet enable you to log and display PHP errors at your will. The current configuration is ideal for production sites, but you may want to enable PHP error display for development purposes. See the code comments for more information on changing these settings.

Cool tips

A couple of notes regarding this method.. First, if you place the following definition to your wp-config.php file, all WordPress debug errors will also be written to your php-errors.log file:

define('WP_DEBUG', true); // enable debugging mode

Also note that the code used for this example demonstrates a very basic implementation. You may add any number of additional @ini_set() directives to enhance and customize your error-logging system as needed.

Method 2: Error Logging via the PHP initiation file

If you have access to your site’s php.ini file, or if you are able to implement “per-directory” initiation files, this method will enable you to monitor PHP errors for any website, not just those powered by WordPress. The process is very similar to the previous method, and requires the following two steps:

Step 1: Create a log file

Step 2: Add the magic code

Next, open your site’s php.ini file and add the following code:

;;; log php errors
display_startup_errors = false
display_errors = false
html_errors = false
log_errors = true
track_errors = true
error_log = /home/path/logs/php-errors.log
error_reporting = E_ALL | E_STRICT
log_errors_max_len = 0

As before, this code is configured for optimal error-handling for production servers. The only thing that you need to edit is the absolute directory path for your log file. During site development, you may want to change some of the variables to enable error display, startup errors, repeat errors, and so forth. For more information on these directives, and for a more in-depth guide to logging errors with PHP, check out my article at Perishable Press, Advanced PHP Error Handling via PHP.

Method 3: Error Logging via the HTAccess file

Last but not least, let’s look at how to enable PHP error-logging via HTAccess. This method works great if HTAccess files are enabled on your site, and will enable you to log PHP errors on any site, not just those powered by WordPress. The process is very similar to the previous method, and requires the following two steps:

Step 1: Create a log file

Step 2: Add the magic code

Next, open your site’s root .htaccess file and add the following code:

# log php errors
php_flag display_startup_errors off
php_flag display_errors off
php_flag html_errors off
php_flag  log_errors on
php_value error_log /home/path/logs/php-errors.log

As before, this code is configured for optimal error-handling for production servers. The only thing that you need to edit is the absolute directory path for your log file. During site development, you may want to change some of the variables to enable error display, startup errors, repeat errors, and so forth. For more information on these directives, and for a more in-depth guide to logging PHP errors via HTAccess, check out my article at Perishable Press, Advanced PHP Error Handling via htaccess.

Troubleshooting Tips

To determine the absolute path of your log file, upload a PHP with the following code to the same directory and open it in a browser:

Depending on your server configuration, you may need to use method #1 or #2 if you are running PHP5. Certain dual-PHP setups and other configurations may require any php_value directives to be placed in a php.ini file instead of htaccess.

An easy way to test that your error-logging system is working is to trigger a few basic PHP errors. To do so, create a PHP file and add something that will trigger an error, for example:

Lastly, if you are triggering errors but nothing is being written to your log file, triple-check that the file is writable by the server. Depending on your particular server configuration, you may need to increase the permissions level of the file. If you have to run with a setting of “777” (full permissions), definitely make sure that the log file is placed above the web-accessible root directory of your site.

Wrap it up then

With one of these three PHP error-logging techniques, you have everything you need to implement easy, automatic error-logging for your website. Everything happens quietly behind the scenes, so remember to keep an eye on things by checking your log file periodically. Doing so will enable you to ensure a well-performing site and the best possible experience for your visitors.