What is mod_rewrite and How Do You Use It?

Why Rewrite URLs

There are lots of reasons to rewrite URLs, but the simplest reason is to give you more control of your Web site. Using the mod_rewrite module for Apache, you can control the URLs your customers see, what pages they can access, control over who sees what pages and much more. This article won't go into the really complex aspects of mod_rewrite, but if you need to change a lot of URLs on your site or you don't want to expose what server programming you're using, mod_rewrite can be a powerful tool, and this tutorial will get you started.

What is Required to Rewrite a URL

There are only a few things that are required to allow you to rewrite a URL using mod_rewrite.

1. Apache version 1.2 or higher with the mod_rewrite module installed. Since this is generally installed by default, you should be good to go if Apache 1.2 is on your system. If not, consult your system administrator.
2. Write access to the .htaccess file in your Web directory.

Ways to Use mod_rewrite

The mod_rewrite module works by caching requests for URLs. The cached URLs are then compared to rules written in the .htaccess file (or the httpd.conf file) and for matches, applies changes to the URL. Then the request is reprocessed with the changes applied. The important thing to remember is that with mod_rewrite nothing new has been created. All mod_rewrite does is change how the server looks at whatever is being requested - such as the file name. You can use mod_rewrite to do the following:

• When someone requests the file /index.htm in the directory, have them see the file default.html. But don't tell them they're seeing the new file. (In other words, leave the URL they typed in alone.)
• When someone requests the file /file.htm in the directory, have them see the file new-file.html and let them know that the URL has changed (through HTTP status codes).
• If you have a page that uses parameters, but you want them hidden. You can use mod_rewrite to change /page/new/ to /parameters.php?page=new. The first page (/page/new/) does not exist on your server, but /parameters.php does.

Regular Expressions and mod_rewrite

mod_rewrite relies on regular expressions or regex to define the matches. While it is certainly possible to set up a mod_rewrite rule for each individual page you want selected, that would be very time consuming, and chances are you'd miss one. By using regular expressions, you can define wildcards so that more pages will be caught by one rule and sent to the correct place.

For example: If you have a directory /oldpages that you have moved all the files in it to a new location /newpages you can set up a rule for every file in that directory. But if there are hundreds or thousands of pages, that will take a long time. Instead, you could write a rule that looked something like /oldpages/* and that would match every file in that directory - no matter what someone put after /oldpages/, the rule would match.

There are a lot of rules in regular expressions, but here are a few basic ones:

• * (asterisk) - a wildcard that matches everything. Use it carefully.
• . (period) - the dot is a wildcard that only matches one character. Similar codes are + which matches 1 or more of the character directly preceding it and ? matches 0 or 1 of the character directly preceding it.
• [ ] - matches a grouping of characters. For instance [A-Z] matches a capital letter, [a-z] matches a lower case letter, and [0-9] matches a number.

Regular expressions are very complicated, and there are many great articles on the topic. This forum entry describes more regular expressions for mod_rewrite in detail. If you're interested in more advanced regular expressions, I highly recommend the book Mastering Regular Expressions by Jeffrey E. F. Friedl.

Write Your First mod_rewrite Rule

Request for index.htm points to default.html

1. Make sure that the file default.html exists on your Web server
2. Edit the file /.htaccess using a text editor
3. Put the following into the .htaccess file:

   RewriteRule index.htm default.html

Point file.html to newfile.html and Note the Change

1. Make sure that the file newfile.html exists on your Web server
2. Edit the file /.htaccess using a text editor
3. Put the following into the .htaccess file:

   RewriteRule file.htm newfile.html [R=301,L]

Change /page/new to /parameters.php?page=new (Hide the Parameters)

1. Make sure that the file parameters.php exists on your Web server
2. Edit the file /.htaccess using a text editor
3. Put the following into the .htaccess file (all one line):

   RewriteRule ^/([a-z]+)/([a-z]+)$ /parameter.php?$1=$2