Creating Custom Error Pages on Apache Servers | WebReference

Creating Custom Error Pages on Apache Servers

By Lee Underwood


It's almost inevitable that on any given Web site someone, at some time, is going to be directed to a nonexistent URL, either through a mistyped address, an incorrect link or due to an incorrectly installed script. Usually, on a server running the Apache software, the visitor will receive the standard error page. For the most part, this type of information doesn't really mean anything to the visitor. In addition, the default error page does not offer any navigational options. The only navigation method available to the visitor is the browser's back button. While it is probably safe to assume that most people today know how to use the back button, a good user interface should allow other options.

It's important to remember when designing Web sites that many people today expect to quickly find what they need on the Web. If the navigation system on a Web site is not clear, they just might leave quicker than they arrived. They don't really care if there was an error on the server, much less if it's a 404 or 500. Some people may even be a bit intimidated, causing them to mistakenly believe that they have received a virus from the site when, in fact, they may have just left a letter out of the name of the page, e.g., entering "link.html" instead of "links.html."

Basic Apache Error Codes Explained

There are 57 Apache HTTP status response codes. Most of them will never show up in the type of errors we are talking about here. For our purposes, we will cover just five. They are explained as follows, with a link showing what the page looks like (see "Hypertext Transfer Protocol — HTTP/1.1" for additional details):

400 — Bad Request
The server did not understand the request due to bad syntax.
401 — Unauthorized
The visitor must by authorized (e.g., have a password) to access the page.
403 — Forbidden
The server understood the request but was unable to execute it. This could be due to an incorrect username and/or password or the server requires different input.
404 — Not Found
The server cannot find a matching URL.
500 — Internal Server Error
The server encountered an unexpected condition which prevented it from fulfilling the request.

Since it's our job to make the visitor's experience on our Web sites as pleasant as possible, let's look into one method for accomplishing that, with respect to the Apache error codes.

A Brief Introduction to .htaccess Files

The .htaccess file is a Web server configuration file that contains commands used by the server that tells it how to behave in certain instances. One of the most common uses of an .htaccess file is to restrict access to certain files or directories on the server through password protection. It is also used to redirect users automatically, ban server access to certain IP addresses, and, as in our case, to call a custom designed error page. Apache Web servers, and other NCSA compliant Web servers can use .htaccess files. (If you cannot find the file on your server you may need to create one, as it's not required for server operation. Also, you may need to change the options in your FTP program, or whatever you use to access your Web site, so that is it viewable. Many file transfer programs turn off viewing files that begin with a dot ["."] by default.)

The Apache Software Foundation has written a basic tutorial for creating .htaccess files. It should get you up and running without any problems. However, for our purposes, if you don't already have one, just create a blank file and name it .htaccess. Its contents will be discussed later. If you do have one, just add the code listed later in this tutorial. If you have any questions about creating and using .htaccess files, you can always find help over on our forums.

A Simple Error Page Solution

One of the easiest ways to take care of error situations is by the use of custom error pages. Generally, this means that for the typical error, you would need to create a separate page with a separate message. The listing in your .htaccess file (placed in the root directory) might look like this:

That is a very simple method for doing it; however, you will need to create five different files. That's not really that big of a deal but it would be much better if you could just create one file to handle all the errors, automatically.

A Better Error Page Solution

If you look at the following images of some of the custom error pages used on WebReference, you will see that they provide better information and more options for our visitors:

Isn't that much better than the default pages shown at the beginning of this tutorial? If you look closely, you'll see that the URL the visitor attempted to access is shown, along with a few reasons why they were not able to view it. They also are given an option to contact someone at the Web site. In addition, all of the regular navigation is available, as the page is formatted to look like the rest of the Web site, thereby not causing too much alarm to your visitors. You can also place ads on the page for additional traffic, if you like. However, since the person is already a bit frustrated, keeping the page ad free, for the most part, might be a better option.

Let's take a look and see what we need to do to implement these type of error pages. As you'll see, it's not that difficult. The requirements are pretty simple: you must have PHP on your Web server; and you need to make sure that you are allowed to use custom error pages. Most Web hosts running the Apache operating system on their servers can accommodate both of these requirements so they shouldn't really be a problem.

The Basic Script

The script, written in PHP, uses the switch statement to determine which message to display, depending on the error received. The script also includes the option of sending an e-mail notice to a specified e-mail address with the time, error received, requested page and the page they came from. Depending upon the number of errors you receive, you might not want to use this feature as it could cause a large amount of e-mail traffic. The script was created by a company called Sabre Web Design, of Dublin, Ireland.

The complete script is listed on this page.

'Installing' the Script

The complete script is placed directly onto a Web page, in the location where the page content would generally be placed. Doing it in this manner allows the error pages to have the same design as the rest of the site. This can prove to be important many times as some visitors are a bit intimidated when they see this type of page, as I mentioned above.

The only change that is necessary is to the $email variable. You will need to change this to the e-mail address you want the error notices sent to. If you are not going to use this feature, then either delete or comment out the section at the bottom of the script titled, "E-mail section." There are several places in the script that use the $email variable for displaying the e-mail address so that visitor's can contact you. If you don't want to have them do that, just remove the lines in each error code in the script. Another method, if you do want to display the e-mail address but not receive the spam resulting from it is to use graphics with your e-mail address in them. That way the visitor can read it but the spambots can't.

You will then need to add the following lines to your .htaccess file. (This is like the listing above, except that only one page needs to be referenced.) If you upload the page with the script on it to your root directory, then you won't need to make any changes. Otherwise, be sure to change the path to the file, e.g., ErrorDocument 400 /otherDir/errorpage.php.

Then, just upload the page with the script and the .htaccess file to your root directory. Make sure that the file attributes for the page with the script on it are set to "644" (rw-r--r--).

That's it! To test it, just enter a URL to a page that is not actually on your Web site.

Customizing the Script

The sky is the limit as to how you can customize what is displayed on the error page. Francesco Mugnai has a list of customized 404 error pages on his blog. Some of these are very creative and inventive.

See Also

Original: February 19, 2009